docs: update content

Author: timdeschryver

projects/www/src/app/pages/guide/component-store/usage.md

@@ -293,7 +293,7 @@ Effects are used to perform additional validation and get extra information from
   region="updating-state">
 
 ```ts
-  changePageSize(newPageSize: number) {
+changePageSize(newPageSize: number) {
     this.paginatorStore.changePageSize(newPageSize);
   }
   nextPage() {

projects/www/src/app/pages/guide/signals/signal-state.md

@@ -117,34 +117,6 @@ patchState(userState, (state) => ({
 patchState(userState, setFirstName('Stevie'), setAdmin());
 ```
 
-## Using User-Defined Signals
-
-The `signalState` function supports integrating user-defined `WritableSignal` instances as part of the state.
-
-If a root state property is a `WritableSignal`, its value becomes an integral part of the state.
-The SignalState instance and the original signal remain synchronized - updating one will immediately reflect in the other.
-
-```ts
-const name = signal('Jimi Hendrix');
-const userState = signalState({
-  // 👇 Providing an external signal as part of the initial state.
-  name,
-  isAdmin: false,
-});
-
-console.log(userState.name()); // logs: Jimi Hendrix
-
-// Updating the external signal
-name.set('Brian May');
-// reflects the value in the SignalState instance.
-console.log(userState.name()); // logs: Brian May
-
-// Updating the SignalState instance
-patchState(userState, { name: 'Eric Clapton' });
-// reflects the value in the external signal.
-console.log(name()); // logs: Eric Clapton
-```
-
 ## Usage
 
 ### Example 1: SignalState in a Component

projects/www/src/app/pages/guide/signals/signal-store/index.md

@@ -49,28 +49,6 @@ The `BookSearchStore` instance will contain the following properties:
 
 <ngrx-docs-alert type="help">
 
-In addition to plain values, the `withState` feature also accepts user-defined `WritableSignal` instances as part of the state.
-In this case, the SignalStore's state and the original signal remain synchronized - updating one will immediately reflect in the other.
-
-```ts
-import { signalStore, withState } from '@ngrx/signals';
-import { Book } from './book';
-
-const books = signal<Book[]>([]);
-
-const BookSearchStore = signalStore(
-  withState({
-    // 👇 Providing an external signal as part of the initial state.
-    books,
-    isLoading: false,
-  })
-);
-```
-
-</ngrx-docs-alert>
-
-<ngrx-docs-alert type="help">
-
 The `withState` feature also has a signature that takes the initial state factory as an input argument.
 The factory is executed within the injection context, allowing initial state to be obtained from a service or injection token.
 

projects/www/src/app/pages/guide/signals/signal-store/linked-state.md

@@ -1,40 +1,71 @@
 # Linked State
 
-The `withLinkedState` feature enables the creation of state slices that depend on other parts of the state. It supports both implicit and explicit linking.
-
-In the context of the SignalStore, `withLinkedState()` serves as the equivalent to Angular's `linkedSignal()`.
-
-Linked state can be added to the store using the `withLinkedState()` feature. This feature accepts a factory function as an input argument, which is executed within the injection context. The factory should return a dictionary containing:
-
-- Functions that return values, which the SignalStore wraps automatically into a `linkedSignal()`, or
-- `WritableSignal`, which the user can create with `linkedSignal()`.
+The `withLinkedState` feature enables the creation of state slices that depend on other signals.
+This feature accepts a factory function as an input argument, which is executed within the injection context.
+The factory should return a dictionary containing linked state slices, defined as either computation functions or `WritableSignal` instances.
+These linked state slices become an integral part of the SignalStore's state and are treated the same as regular state slices - `DeepSignal`s are created for each of them, and they can be updated using `patchState`.
 
 ## Implicit Linking
 
-The following example shows the implicit notation, where a function returns a value. That function is wrapped into a `linkedSignal()`, which means it is tracked, and if one of the tracked Signals changes, the function is re-executed synchronously.
+When a computation function is provided, the SignalStore wraps it in a `linkedSignal()`.
+As a result, the linked state slice is updated automatically whenever any of its dependent signals change.
 
-<ngrx-code-example header="options-store.ts">
+<code-tabs linenums="true">
+<code-pane header="options-store.ts">
 
 ```ts
-import {
-  signalStore,
-  withLinkedState,
-  withState,
-} from '@ngrx/signals';
+import { patchState, signalStore, withLinkedState, withState } from '@ngrx/signals';
 
 export const OptionsStore = signalStore(
-  withState({ options: [1, 2, 3] }),
-  withLinkedState(({ options }) => ({
-    selectedOption: () => options()[0] ?? undefined,
-  }))
+    withState({ options: [1, 2, 3] }),
+    withLinkedState(({ options }) => ({
+        // 👇 Defining a linked state slice.
+        selectedOption: () => options()[0] ?? undefined,
+    })),
+    withMethods((store) => ({
+        setOptions(options: number[]): void {
+            patchState(store, { options });
+        },
+        setSelectedOption(selectedOption: number): void {
+            // 👇 Updating a linked state slice.
+            patchState(store, { selectedOption });
+        },
+    }),
 );
 ```
 
-</ngrx-code-example>
+</code-pane>
+
+<code-pane header="option-list.ts">
+
+```ts
+@Component({
+  // ... other metadata
+  providers: [OptionsStore],
+})
+export class OptionList {
+  readonly store = inject(OptionsStore);
+
+  constructor() {
+    console.log(this.store.selectedOption()); // logs: 1
+
+    this.store.setSelectedOption(2);
+    console.log(this.store.selectedOption()); // logs: 2
+
+    this.store.setOptions([4, 5, 6]);
+    console.log(this.store.selectedOption()); // logs: 4
+  }
+}
+```
+
+</code-pane>
+</code-tabs>
 
 ## Explicit Linking
 
-The explicit notation requires users to execute `linkedSignal()` manually; however, it offers the advantage of using the more powerful version of `linkedSignal()`, which includes the `source` and `computation` options.
+The `withLinkedState` feature also supports providing `WritableSignal` instances as linked state slices.
+This can include signals created using `linkedSignal()` with `source` and `computation` options, as well as any other `WritableSignal` instances.
+In both cases, the SignalStore and the original signal remain fully synchronized - updating one immediately reflects in the other.
 
 <ngrx-code-example header="options-store.ts">