pasika 0.1.0 → 0.1.4

package/docs/code-organization-guide/rules/component-placement-rule.md

@@ -0,0 +1,135 @@
+# Component Placement Rule
+
+Without clear placement, it is hard to tell where a component belongs and reuse can create tangled dependencies. This rule gives each component a specific place in the application structure.
+
+- A routing UI file is a Next.js App Router UI file, excluding request handlers and metadata files. A Next.js `layout.tsx` routing UI file MAY render the layout required by its route segment and `children`. Any other routing UI file MAY import root support modules and directly render one feature component, one composition, or one shared component, but MUST NOT own state, callbacks, effects, or page layout.
+- A routing UI file other than `layout.tsx` that needs state, callbacks, effects, or page layout MUST delegate that work to a component in `src/compositions/`.
+- Any other component that imports from two or more feature folders MUST live in `src/compositions/` and is, by definition, a composition.
+- A component whose only consumers are routing files and that does not import from two or more feature folders MUST live in the feature folder whose behavior it implements. A component implements a feature when it reads that feature's data or exposes that feature's actions. If it implements no feature and only one routing file imports it, it MUST introduce a new feature folder for that route; if routing files for two or more routes import it, it MUST live in `src/shared/`. This rule does not apply to Next.js routing files themselves.
+- A component with at least one consumer other than a routing file MUST live in the closest common folder (CCF) of its non-routing consumers.
+- A new component with no consumers and fewer than two feature-folder imports MUST start in the existing feature folder it belongs to, or in a new feature folder when it introduces a new feature. A new component with no feature-specific behavior or data MAY start in `src/shared/` only when it imports no feature folders; otherwise it starts in the feature it imports from.
+- Imports from routing files in `src/app/` MUST NOT count as component consumers or affect CCF calculation.
+- Imports from configuration modules MUST NOT count as component consumers or affect CCF calculation.
+- When a component is imported both inside and outside `src/compositions/`, its CCF MUST be calculated only from imports outside `src/compositions/`.
+- When a component is imported only in `src/compositions/`, its CCF MUST be calculated from those imports.
+- When a component’s CCF is `src/features/`, it MUST live in `src/shared/`.
+- When a component’s CCF is `src/`, it MUST live in `src/shared/`.
+- When a component’s CCF is a nested component directory, it MUST start flat in that directory unless the Folder Nesting Rule requires nesting.
+- When a component’s CCF is a feature folder, `src/compositions/`, or `src/shared/`, it MUST start flat in that folder unless the Folder Nesting Rule requires nesting.
+- `src/app/` MUST contain [Next.js App Router framework-convention files and assets](https://nextjs.org/docs/app/getting-started/project-structure#routing-files), plus styles required by routing files, but MUST NOT contain ordinary components or support folders.
+- A JavaScript or TypeScript module under `src/app/` MUST NOT import modules under `src/` except from `src/compositions/`, `src/features/`, `src/shared/`, and root support folders.
+- A JavaScript or TypeScript module under `src/compositions/` MUST NOT import modules under `src/` except from `src/compositions/`, feature folders, `src/shared/`, and root support folders.
+- A JavaScript or TypeScript module in a feature folder MUST NOT import modules under `src/` except from the same feature folder, `src/shared/`, and root support folders.
+- A JavaScript or TypeScript module under `src/shared/` MUST NOT import modules under `src/` except from `src/shared/` and root support folders.
+- A JavaScript or TypeScript module in a root support folder MUST NOT import modules under `src/` except from root support folders. Any module under `src/config/<config-name>/` MAY also import files under that same configuration-object directory.
+- ESLint MUST enforce these import restrictions for JavaScript and TypeScript modules under `src/`.
+
+## Incorrect — Cross-Feature Component Duplicated
+
+```text
+src/features/
+├── donation/
+│   ├── DonationCard.tsx
+│   └── status-badge.tsx
+└── stream/
+    ├── StreamCard.tsx
+    └── status-badge.tsx
+```
+
+Why: two feature folders contain duplicate copies because neither feature may import from the other.
+
+## Correct — Cross-Feature Component in `src/shared/`
+
+```text
+src/
+├── features/
+│   ├── donation/
+│   │   └── DonationCard.tsx
+│   └── stream/
+│       └── StreamCard.tsx
+└── shared/
+    └── status-badge.tsx
+```
+
+Why: the component's CCF is `src/features/`, so it lives in `src/shared/`.
+
+## Incorrect — Multi-Feature Composition Inside One Feature
+
+```tsx
+// src/features/billing/billing-aggregate-view.tsx
+import { BillingPanel } from "./BillingPanel";
+import { HomeBanner } from "@/features/home/HomeBanner";
+```
+
+Why: the component imports from two feature folders, so it cannot live in either feature folder.
+
+## Correct — Multi-Feature Component in `src/compositions/`
+
+```tsx
+// src/compositions/billing-aggregate-view.tsx
+import { BillingPanel } from "@/features/billing/BillingPanel";
+import { HomeBanner } from "@/features/home/HomeBanner";
+```
+
+Why: the component imports from two feature folders, so it lives in `src/compositions/`.
+
+## Incorrect — Ordinary Component Under `src/app/`
+
+```text
+src/app/contact/
+├── _components/
+│   └── contact-page-content.tsx
+└── page.tsx
+```
+
+Why: the route folder contains ordinary component structure even though `src/app/` is reserved for framework routing files.
+
+## Correct — Thin Route Imports a Page Composition
+
+```text
+src/
+├── app/contact/
+│   └── page.tsx
+├── compositions/
+│   └── contact-page-content.tsx
+└── features/
+    ├── contact/
+    │   └── contact-information.tsx
+    └── location/
+        └── office-location.tsx
+```
+
+```tsx
+// src/compositions/contact-page-content.tsx
+import { ContactInformation } from "@/features/contact/contact-information";
+import { OfficeLocation } from "@/features/location/office-location";
+import { locales } from "@/locales";
+
+export function ContactPageContent(): React.JSX.Element {
+  return (
+    <main data-testid="contact-page-content">
+      <header>
+        <h1>{locales.contactPageTitle}</h1>
+        <p>{locales.contactPageDescription}</p>
+      </header>
+      <section>
+        <h2>{locales.contactInformationHeading}</h2>
+        <ContactInformation />
+      </section>
+      <section>
+        <h2>{locales.officeLocationHeading}</h2>
+        <OfficeLocation />
+      </section>
+    </main>
+  );
+}
+
+// src/app/contact/page.tsx
+import { ContactPageContent } from "@/compositions/contact-page-content";
+
+export default function Page(): React.JSX.Element {
+  return <ContactPageContent />;
+}
+```
+
+Why: the routing file remains thin while the page composition provides the contact page layout and combines components from two feature folders.

package/docs/code-organization-guide/rules/configuration-rule.md

@@ -0,0 +1,42 @@
+# Configuration Rule
+
+Configuration objects centralize values that control application behavior. This rule keeps each object and the files that only support it together in `src/config/`.
+
+- A configuration object is an app-wide object that selects or parameterizes application behavior. Feature options and domain values are not configuration objects.
+- All configuration objects MUST live in `src/config/`.
+- A configuration object MUST use `src/config/<config-name>/index.ts`.
+- A configuration support file is a hook, type, schema, constant, or utility used only to implement one configuration object; config-only extraction applies even with one consumer.
+- A configuration support file MUST live in its matching dedicated folder under `src/config/<config-name>/`.
+- A configuration support file remains in that configuration-object directory while every consumer is in that directory; it MUST move to its matching root support folder at the root CCF when any consumer is outside it.
+
+## Incorrect — Supporting Schema Outside Its Config Folder
+
+```text
+src/config/
+├── home-feed/
+│   └── index.ts
+└── home-feed-schema.ts
+```
+
+Why: the schema sits outside the `home-feed/` configuration folder.
+
+## Correct — Configuration Object with Its Supporting Schema
+
+```text
+src/config/
+└── home-feed/
+    ├── index.ts
+    └── schemas/
+        └── index.ts
+```
+
+```ts
+// src/config/home-feed/index.ts
+import { homeFeedConfigSchema } from "./schemas";
+
+export const homeFeedConfig = homeFeedConfigSchema.parse({
+  freshVideoMaxAgeDays: 7,
+});
+```
+
+Why: the configuration object and its supporting schema are grouped in the same configuration folder.

package/docs/code-organization-guide/rules/constants-rule.md

@@ -0,0 +1,77 @@
+# Constants Rule
+
+Duplicated constants are hard to keep in sync, while extracting every single-use value creates unnecessary files. This rule keeps reused constants in one module and leaves single-use values close to their consumer.
+
+- A constant is an exported or reused fixed domain value; local literals and implementation values are not constants for this rule. A configuration object is not a constant for this rule.
+- Except for a constant used only to implement one configuration object, a constant MUST stay in the file that uses it until another file imports it.
+- A constant used only to implement one configuration object MUST live in that object's `constants/` folder.
+- Extracted constants MUST live in a `constants/` folder at the closest common folder (CCF) of their consumers.
+- A `constants/index.ts` MAY define its exports directly.
+- Consumers MUST import extracted constants through the `constants/index.ts` at their scope.
+- Constants that are used together MAY be grouped in a file with a kebab-case name and named-re-exported from `constants/index.ts`.
+- When a `constants/` folder uses grouped files, its `index.ts` MUST only named-re-export those files.
+- When a constant's CCF is `src/features/`, it MUST move to `src/constants/`.
+
+## Incorrect — Constant Imported Without `constants/index.ts`
+
+```ts
+// src/features/billing/constants/max-retries.ts
+export const maxRetries = 3;
+```
+
+```ts
+// src/features/billing/hooks/use-retry-payment.ts
+import { maxRetries } from "../constants/max-retries";
+```
+
+Why: the consumer bypasses the feature's `constants/index.ts`.
+
+## Correct — Grouped Constants Re-Exported from `constants/index.ts`
+
+```ts
+// src/features/billing/constants/retry.ts
+export const maxRetries = 3;
+export const retryDelayMs = 1_000;
+
+// src/features/billing/constants/index.ts
+export { maxRetries, retryDelayMs } from "./retry";
+```
+
+```ts
+// src/features/billing/hooks/use-retry-payment.ts
+import { maxRetries } from "../constants";
+```
+
+Why: the constants are available through the feature's `constants/index.ts`.
+
+## Incorrect — Feature and Composition Constant Kept in a Feature
+
+```ts
+// src/features/billing/constants/index.ts
+export const paymentRetryDelayMs = 1_000;
+
+// src/features/billing/hooks/use-retry-payment.ts
+import { paymentRetryDelayMs } from "../constants";
+
+// src/compositions/BillingDashboard.tsx
+import { paymentRetryDelayMs } from "@/features/billing/constants";
+```
+
+Why: the feature and composition have `src/` as their CCF, but the constant remains in the billing feature.
+
+## Correct — Feature and Composition Constant in `src/constants/`
+
+```ts
+// src/constants/index.ts
+export const paymentRetryDelayMs = 1_000;
+```
+
+```tsx
+// src/features/billing/hooks/use-retry-payment.ts
+import { paymentRetryDelayMs } from "@/constants";
+
+// src/compositions/BillingDashboard.tsx
+import { paymentRetryDelayMs } from "@/constants";
+```
+
+Why: the feature and composition have `src/` as their CCF, so the constant lives in `src/constants/`.

package/docs/code-organization-guide/rules/exports-and-imports-rule.md

@@ -0,0 +1,81 @@
+# Exports and Imports Rule
+
+Without consistent export and import styles, it is harder to tell what a file contains and how other files should import from it. This rule gives each file type a predictable export style and keeps import paths consistent.
+
+- Static JavaScript and TypeScript modules under `src/` MUST use named exports unless a framework or third-party package requires a different export style for a specific file.
+- Static imports under `src/` MUST use relative paths for the same folder, a direct subfolder, or one folder up.
+- Static imports under `src/` MUST use the `@/*` alias for anything beyond one folder up.
+- ESLint MUST enforce this rule's export and static import restrictions under `src/`.
+
+## Incorrect — Single-Export Utility Uses a Default Export
+
+```ts
+// src/utils/format-duration.ts
+export default function formatDuration(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${minutes}:${String(remainder).padStart(2, "0")}`;
+}
+```
+
+Why: files use named exports even when they expose one item.
+
+## Correct — Single-Export Utility Uses a Named Export
+
+```ts
+// src/utils/format-duration.ts
+export function formatDuration(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${minutes}:${String(remainder).padStart(2, "0")}`;
+}
+```
+
+Why: the utility uses the same named-export form as every other file that does not have a package-required export contract.
+
+## Incorrect — Deep Relative Path
+
+```ts
+// src/features/stream/StreamBoard/schedule.ts
+import { debounce } from "../../../utils/debounce";
+```
+
+Why: reaching more than one folder up hides the cross-scope dependency in relative path traversal.
+
+## Correct — Alias Across Scopes and Relative Paths Nearby
+
+```ts
+// src/features/stream/StreamBoard/schedule.ts
+import { debounce } from "@/utils/debounce";
+import { formatSlot } from "./utils/format-slot";
+import { type StreamSlot } from "./types";
+import { buildSchedule } from "../schedule-builder";
+```
+
+Why: the alias identifies the distant dependency while nearby files keep short relative paths.
+
+## Incorrect — Next.js Page Uses a Named Export
+
+```tsx
+// src/app/contact/page.tsx
+import { locales } from "@/locales";
+
+export function Page(): React.JSX.Element {
+  return <main>{locales.contactUs}</main>;
+}
+```
+
+Why: Next.js requires a `page.tsx` file to default-export its page component.
+
+## Correct — Next.js Page Uses a Default Export
+
+```tsx
+// src/app/contact/page.tsx
+import { locales } from "@/locales";
+
+export default function Page(): React.JSX.Element {
+  return <main>{locales.contactUs}</main>;
+}
+```
+
+Why: the page follows the export contract Next.js requires.

package/docs/code-organization-guide/rules/folder-nesting-rule.md

@@ -0,0 +1,83 @@
+# Folder Nesting Rule
+
+Without nesting, exclusive children can look reusable and their relationship to the parent is easy to miss in review. This rule groups them with their parent and keeps them out of the folder's public API.
+
+- An exclusive child component is imported only by its parent component or descendants in the parent's folder. A flat component MUST be nested in a folder with the same name when it gains one or more exclusive child components.
+- A child that gains a consumer outside its parent's folder MUST move according to the Component Placement Rule, including that rule's CCF consumer exclusions.
+- A component MUST NOT be nested only because it has support files.
+- A nested component's support files MUST live in its folder.
+- The nested folder's `index.ts` MUST named-re-export the nested component and MUST NOT re-export its exclusive children.
+
+## Incorrect — Exclusive Children Kept Flat
+
+```text
+src/features/blog/
+  BlogPage.tsx                # owns exclusive children
+  blog-header.tsx             # exclusive child — no sibling needs it
+  blog-footer.tsx             # exclusive child — no sibling needs it
+  hooks/
+    use-blog-filter.ts        # used only by BlogPage
+```
+
+Why: `BlogPage` owns children that no sibling uses, but all three files sit as flat siblings. Nothing in the tree shows that `blog-header.tsx` and `blog-footer.tsx` belong to `BlogPage` rather than to any other component in the folder.
+
+## Correct — Exclusive Children Nested
+
+```text
+src/features/blog/
+  BlogPage/
+    index.ts                  # re-exports only BlogPage.tsx
+    BlogPage.tsx
+    blog-header.tsx           # not re-exported from index.ts
+    blog-footer.tsx           # not re-exported from index.ts
+    hooks/
+      use-blog-filter.ts
+```
+
+Why: nesting `BlogPage` into `BlogPage/` makes the parent–child relationship visible in the filesystem, lets the children stay scoped to their concrete consumer, and gives the folder a barrel that re-exports only the nested component.
+
+## Incorrect — Support Files Cause Unnecessary Nesting
+
+```text
+src/features/blog/
+  BlogPage/
+    index.ts
+    BlogPage.tsx
+    hooks/
+      use-blog-filter.ts
+```
+
+Why: support files alone do not make `BlogPage` a nested component.
+
+## Correct — Support Files Keep a Component Flat
+
+```text
+src/features/blog/
+  BlogPage.tsx
+  hooks/
+    use-blog-filter.ts
+```
+
+Why: without exclusive children, `BlogPage` stays flat and its support files remain at the feature scope.
+
+## Incorrect — Exclusive Child Re-Exported
+
+```ts
+// src/features/blog/BlogPage/index.ts
+export { BlogPage } from "./BlogPage";
+export { BlogHeader } from "./blog-header";
+```
+
+Why: the barrel re-exports the child as well as the nested component, so outside consumers can import `blog-header.tsx` through `index.ts` and the child stops being exclusive to `BlogPage`.
+
+## Correct — Only the Nested Component Re-Exported
+
+```tsx
+// src/features/blog/BlogPage/index.ts
+export { BlogPage } from "./BlogPage";
+
+// src/features/blog/BlogPage/BlogPage.tsx
+import { BlogHeader } from "./blog-header";
+```
+
+Why: the barrel exposes only the nested component, so it does not expose the child.

package/docs/code-organization-guide/rules/hook-extraction-rule.md

@@ -0,0 +1,142 @@
+# Hook Extraction Rule
+
+Keeping every hook inline makes components bloated, while extracting every hook adds indirection without benefit. This rule defines concrete reuse and imperative-complexity triggers for extraction.
+
+- A custom hook MUST be extracted to its own file when two or more consumers use it.
+- A custom hook used only to implement one configuration object MUST live in that object's `hooks/` folder.
+- A custom hook with exactly one consumer MUST be extracted when it contains two or more imperative categories and can be described as one coherent behavior.
+- An extracted custom hook MUST live in a `hooks/` folder at the closest common folder (CCF) of its consumers.
+- When a custom hook's CCF is `src/features/`, it MUST move to `src/hooks/`.
+- The imperative categories MUST be subscriptions, external I/O and persistence, DOM manipulation, or resource lifecycle.
+- One operation MAY count in only one imperative category; use its primary purpose when categories overlap.
+- Subscriptions MUST include event listeners and registration or cleanup APIs such as `on()` and `off()`.
+- External I/O and persistence MUST include network requests, asynchronous reads or writes, and browser storage.
+- DOM manipulation MUST include imperative APIs such as `focus()`, `classList`, observers, or imperative rendering.
+- Resource lifecycle MUST include setup and teardown APIs such as `load()`, `destroy()`, or `dispose()`.
+- A custom hook with one consumer that does not meet the two-category threshold MUST stay inline in its consumer module, unless it is used only to implement one configuration object.
+
+## Incorrect — Two Imperative Categories Left Inline
+
+```tsx
+// src/features/player/Player.tsx
+export function Player({ src }: PlayerProps): React.JSX.Element {
+  useEffect(() => {
+    player.on("play", handlePlay);
+    player.on("pause", handlePause);
+    player.load(src);
+
+    return () => {
+      player.off("play", handlePlay);
+      player.off("pause", handlePause);
+      player.destroy();
+    };
+  }, [src]);
+
+  return <PlayerView />;
+}
+```
+
+Why: one coherent player-setup behavior combines subscriptions with resource lifecycle, so leaving it inline crosses the two-category threshold.
+
+## Correct — Complex Single-Use Hook Extracted
+
+```ts
+// src/features/player/hooks/use-player-setup.ts
+export function usePlayerSetup(src: string): void {
+  useEffect(() => {
+    player.on("play", handlePlay);
+    player.on("pause", handlePause);
+    player.load(src);
+
+    return () => {
+      player.off("play", handlePlay);
+      player.off("pause", handlePause);
+      player.destroy();
+    };
+  }, [src]);
+}
+```
+
+```tsx
+// src/features/player/Player.tsx
+import { usePlayerSetup } from "./hooks/use-player-setup";
+
+export function Player({ src }: PlayerProps): React.JSX.Element {
+  usePlayerSetup(src);
+  return <PlayerView />;
+}
+```
+
+Why: the named hook owns the subscription and resource lifecycle for one coherent behavior, keeping the component focused on rendering.
+
+## Incorrect — Reused Hook Kept Inline
+
+```tsx
+// src/features/billing/invoice.tsx
+const useInvoiceSort = (invoices: Invoice[]): Invoice[] => {
+  return useMemo(() => invoices.toSorted(byDate), [invoices]);
+};
+
+// src/features/billing/invoice-summary.tsx
+const useInvoiceSort = (invoices: Invoice[]): Invoice[] => {
+  return useMemo(() => invoices.toSorted(byDate), [invoices]);
+};
+```
+
+Why: two components use the same hook behavior, so keeping it inline duplicates it.
+
+## Correct — Reused Hook Extracted
+
+```ts
+// src/features/billing/hooks/use-invoice-sort.ts
+export function useInvoiceSort(invoices: Invoice[]): Invoice[] {
+  return useMemo(() => invoices.toSorted(byDate), [invoices]);
+}
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import { useInvoiceSort } from "./hooks/use-invoice-sort";
+
+// src/features/billing/invoice-summary.tsx
+import { useInvoiceSort } from "./hooks/use-invoice-sort";
+```
+
+Why: the hook has two consumers, so it has its own file.
+
+## Incorrect — Simple Single-Use Hook Extracted
+
+```ts
+// src/features/billing/hooks/use-invoice-sort.ts
+export function useInvoiceSort(invoices: Invoice[]): Invoice[] {
+  return useMemo(() => invoices.toSorted(byDate), [invoices]);
+}
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import { useInvoiceSort } from "./hooks/use-invoice-sort";
+
+export function Invoice({ invoices }: InvoiceProps): React.JSX.Element {
+  const sortedInvoices = useInvoiceSort(invoices);
+  return <InvoiceList invoices={sortedInvoices} />;
+}
+```
+
+Why: the hook has one consumer and no imperative category, so its separate file adds indirection before an extraction trigger exists.
+
+## Correct — Simple Single-Use Hook Inline
+
+```tsx
+// src/features/billing/invoice.tsx
+const useInvoiceSort = (invoices: Invoice[]): Invoice[] => {
+  return useMemo(() => invoices.toSorted(byDate), [invoices]);
+};
+
+export function Invoice({ invoices }: InvoiceProps): React.JSX.Element {
+  const sortedInvoices = useInvoiceSort(invoices);
+  return <InvoiceList invoices={sortedInvoices} />;
+}
+```
+
+Why: the hook stays beside its sole consumer until reuse or imperative complexity provides a mechanical extraction trigger.

package/docs/code-organization-guide/rules/interactive-component-rule.md

@@ -0,0 +1,100 @@
+# Interactive Component Rule
+
+Large component files need a clear way to decide what to extract first. This rule treats interactive elements as meaningful component boundaries instead of extracting arbitrary layout elements.
+
+- An [interactive HTML element](https://html.spec.whatwg.org/multipage/dom.html#interactive-content) MUST be extracted to a component with a descriptive name unless it is the top-level native element returned by the component that renders it in every rendered result.
+
+## Incorrect — Interactive Element Kept Inline
+
+```tsx
+// src/features/layout/header-section.tsx
+import { locales } from "@/locales";
+
+export function HeaderSection({
+  onMenuClick,
+  searchPlaceholder,
+}: {
+  onMenuClick: () => void;
+  searchPlaceholder: string;
+}): React.JSX.Element {
+  return (
+    <header className="flex items-center justify-between px-6 py-4">
+      <h1 className="text-2xl">{locales.layout.headerTitle}</h1>
+
+      <button onClick={onMenuClick} aria-label={locales.layout.openMenu}>
+        <Icon name="menu" />
+      </button>
+
+      <input type="search" placeholder={searchPlaceholder} />
+    </header>
+  );
+}
+```
+
+Why: the interactive elements remain mixed into `HeaderSection` instead of having their own components.
+
+## Correct — Interactive Element Extracted
+
+```text
+src/features/layout/
+  header-section/
+    index.ts                  # re-exports only header-section.tsx
+    header-section.tsx
+    menu-button.tsx           # exclusive child — imported directly
+    search-field.tsx          # exclusive child — imported directly
+```
+
+```tsx
+// src/features/layout/header-section/menu-button.tsx
+type MenuButtonProps = React.ComponentProps<"button">;
+
+export function MenuButton({ onClick, ...props }: MenuButtonProps): React.JSX.Element {
+  return (
+    <button {...props} onClick={onClick}>
+      <Icon name="menu" />
+    </button>
+  );
+}
+```
+
+```tsx
+// src/features/layout/header-section/search-field.tsx
+type SearchFieldProps = Omit<React.ComponentProps<"input">, "type">;
+
+export function SearchField(props: SearchFieldProps): React.JSX.Element {
+  return <input {...props} type="search" />;
+}
+```
+
+```tsx
+// src/features/layout/header-section/header-section.tsx — now imports both interactive units instead of inline JSX
+
+import { MenuButton } from "./menu-button";
+import { SearchField } from "./search-field";
+import { cn } from "@/utils/cn";
+import { locales } from "@/locales";
+
+type HeaderSectionProps = React.ComponentProps<"header"> & {
+  onMenuClick: () => void;
+  searchPlaceholder: string;
+};
+
+export function HeaderSection({
+  className,
+  onMenuClick,
+  searchPlaceholder,
+  ...props
+}: HeaderSectionProps): React.JSX.Element {
+  return (
+    <header {...props} className={cn("flex items-center justify-between px-6 py-4", className)}>
+      <h1 className="text-2xl">{locales.layout.headerTitle}</h1>
+
+      <MenuButton onClick={onMenuClick} aria-label={locales.layout.openMenu} />
+
+      <SearchField placeholder={searchPlaceholder} />
+    </header>
+  );
+}
+```
+
+Why: each interactive element now has its own descriptive component and forwards native props, leaving `HeaderSection` to compose them.