pasika 0.1.6 → 0.3.0

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

@@ -1,82 +0,0 @@
-# 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. A component MUST stay flat until it has one or more exclusive child components, then MUST be nested in a folder with the same name.
-- 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

@@ -1,141 +0,0 @@
-# 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 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.
-- Each operation MUST count toward only one imperative category.
-- 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 file.
-
-## 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

@@ -1,97 +0,0 @@
-# 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.
-
-## 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>
-      <h1>{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 { locales } from "@/locales";
-
-type HeaderSectionProps = {
-  onMenuClick: () => void;
-  searchPlaceholder: string;
-};
-
-export function HeaderSection({
-  onMenuClick,
-  searchPlaceholder,
-}: HeaderSectionProps): React.JSX.Element {
-  return (
-    <header>
-      <h1>{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, leaving `HeaderSection` to compose them.

package/docs/code-organization-guide/rules/jsx-hygiene-rule.md

@@ -1,67 +0,0 @@
-# JSX Hygiene Rule
-
-JSX should show the component's structure, not its calculations. This rule moves complex expressions before `return` while keeping simple JSX readable.
-
-- Arithmetic, chained built-in method calls, calls to functions declared outside the component, nested ternaries, and conditions containing two or more logical operators MUST be extracted before `return`, including in JSX attributes.
-- An inline expression MAY contain one condition with up to one logical operator, one ternary, or one built-in method call. `cn()` MAY be called inline. An event handler MAY make one call inline.
-
-## Incorrect — Computation in JSX
-
-```tsx
-return (
-  <div>
-    <span>{Math.floor((Date.now() - new Date(record.updatedAt).getTime()) / 86400000)} {locales.daysAgo}</span>
-    <ul>
-      {items
-        .filter((x) => x.active)
-        .sort(byDate)
-        .map(renderItem)}
-    </ul>
-    <p>
-      {formatDate(record.updatedAt, "long")} — {calculateTotal(items)}
-    </p>
-    {isLoading ? <Spinner /> : hasError ? <Error /> : <Content />}
-    {isLoggedIn && hasPermission && isOwner && featureEnabled && <AdminPanel />}
-    <span>{new Date(post.publishedAt).toLocaleDateString()}</span>
-    {Math.round(score * 100)}%
-  </div>
-);
-```
-
-Why: calculations, chained methods, function calls, nested ternaries, and long guards all belong outside the return.
-
-## Correct — Computation Before `return`
-
-```tsx
-const daysSinceUpdate = Math.floor((Date.now() - new Date(record.updatedAt).getTime()) / 86400000);
-const activeItems = items.filter((x) => x.active).sort(byDate);
-const updatedLabel = formatDate(record.updatedAt, "long");
-const total = calculateTotal(items);
-const canShowAdmin = isLoggedIn && hasPermission && isOwner && featureEnabled;
-const publishDate = new Date(post.publishedAt).toLocaleDateString();
-const scorePercent = Math.round(score * 100);
-
-let statusView = <Content />;
-if (isLoading) {
-  statusView = <Spinner />;
-} else if (hasError) {
-  statusView = <Error />;
-}
-
-return (
-  <div>
-    <span>{daysSinceUpdate} {locales.daysAgo}</span>
-    <ul>{activeItems.map(renderItem)}</ul>
-    <p>
-      {updatedLabel} — {total}
-    </p>
-    {statusView}
-    {scorePercent}%
-    <div className={cn("base", isActive && "bg-primary-100")} />
-    {canShowAdmin && <AdminPanel />}
-    <span>{publishDate}</span>
-  </div>
-);
-```
-
-Why: calculations, chained methods, custom function calls, and nested ternaries now resolve before the return, so only simple conditions, single method calls, and `cn()` stay inline.

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

@@ -1,53 +0,0 @@
-# Locales Rule
-
-When locale strings are scattered across components and constants, they are hard to find and keep consistent. This rule keeps them in one central file, puts each feature's strings together, and uses readable keys.
-
-- All locales MUST live in the named `locales` object exported from `src/locales/index.ts`.
-- Locales read only by files in one feature folder MUST live in an object with the camelCase form of its feature folder name (for example, `user-settings` becomes `userSettings`).
-- Locales read by files in more than one feature folder or by `src/shared/`, `src/compositions/`, `src/app/`, or root support folders MUST live at the top level of `locales`.
-- A namespaced locale MUST be read through its full dotted path (`locales.stream.watchLiveStream`).
-- A locale key MUST be camelCase English based on the text, unless a direct translation would be unclear or unwieldy. In that case, it MAY describe the message's purpose instead.
-
-## Incorrect — Flat Feature Locale Keys
-
-```ts
-// src/locales/index.ts
-export const locales = {
-  streamPlayerLiveText: "Дивитись прямий ефір", // describes the element, not the text
-  ctaButton: "Прийняти всі cookies", // describes the element, not the text
-  youSuccessfullySubscribedToUpdates: "Ви успішно підписалися на оновлення", // direct translation — unwieldy
-};
-```
-
-```tsx
-// src/features/stream/stream-player.tsx
-locales.streamPlayerLiveText; // no namespace — collides with any other feature that picks this key
-```
-
-Why: the first two keys describe elements instead of text, the direct translation is unwieldy, and the flat structure does not show that `streamPlayerLiveText` belongs to the stream feature.
-
-## Correct — Namespaced Feature Locale Keys
-
-```ts
-// src/locales/index.ts
-export const locales = {
-  stream: {
-    watchLiveStream: "Дивитись прямий ефір",
-  },
-  acceptAllCookies: "Прийняти всі cookies", // shared — direct text-based key
-  subscriptionConfirmed: "Ви успішно підписалися на оновлення", // shared — describes the message's purpose
-};
-```
-
-```tsx
-// src/features/stream/stream-player.tsx
-locales.stream.watchLiveStream; // namespaced by feature
-
-// src/shared/cookie-banner.tsx
-locales.acceptAllCookies; // shared — read from the top level
-
-// src/shared/subscription-form.tsx
-locales.subscriptionConfirmed; // shared — read from the top level
-```
-
-Why: the stream feature has its own namespace, while shared strings stay at the top level. `acceptAllCookies` is based on the text, while `subscriptionConfirmed` describes the message's purpose instead of using an unwieldy direct translation.

package/docs/code-organization-guide/rules/nameable-visual-concept-rule.md

@@ -1,66 +0,0 @@
-# Nameable Visual Concept Rule
-
-Some groups of elements can be given a clear component name but have no file of their own. This rule recommends extracting those groups into descriptive components.
-
-- A block of elements SHOULD be extracted to a component when one clear name describes the whole block.
-
-## Incorrect — Nameable Visual Block Kept Inline
-
-```tsx
-// src/features/feed/feed-view.tsx
-export function FeedView(): React.JSX.Element {
-  return (
-    <main>
-      <article>
-        <Avatar />
-        <UserName />
-        <PostTimestamp />
-        <PostBody />
-      </article>
-    </main>
-  );
-}
-```
-
-Why: the avatar, username, and timestamp form a message header but remain inline in `FeedView`.
-
-## Correct — Nameable Visual Block Extracted
-
-```text
-src/features/feed/
-  feed-view/
-    index.ts                  # re-exports only feed-view.tsx
-    feed-view.tsx
-    message-header.tsx        # exclusive child — imported directly by feed-view.tsx
-```
-
-```tsx
-// src/features/feed/feed-view/feed-view.tsx
-import { MessageHeader } from "./message-header";
-
-export function FeedView(): React.JSX.Element {
-  return (
-    <main>
-      <article>
-        <MessageHeader />
-        <PostBody />
-      </article>
-    </main>
-  );
-}
-```
-
-```tsx
-// src/features/feed/feed-view/message-header.tsx
-export function MessageHeader(): React.JSX.Element {
-  return (
-    <header>
-      <Avatar />
-      <UserName />
-      <PostTimestamp />
-    </header>
-  );
-}
-```
-
-Why: `MessageHeader` gives the group a clear name and its own file, while `FeedView` only composes it.

package/docs/code-organization-guide/rules/no-mixed-concerns-rule.md

@@ -1,63 +0,0 @@
-# No Mixed Concerns Rule
-
-One component per file keeps components easy to find and change independently. This rule applies the same requirement to copied and generated source.
-
-- A `.tsx` file that defines a component MUST contain exactly one component.
-
-## Incorrect — Two Components in One File
-
-Two components in one file:
-
-```tsx
-// src/features/nav/menu.tsx
-export function Menu(): React.JSX.Element {
-  return (
-    <nav>
-      <MenuItem label="Home" />
-      <MenuItem label="About" />
-    </nav>
-  );
-}
-
-export function MenuItem({ label }: { label: string }): React.JSX.Element {
-  return <a href="#">{label}</a>;
-}
-```
-
-Why: two components share `menu.tsx`, so a reviewer searching for `MenuItem` cannot find it in the file tree.
-
-## Correct — Extracted Child in Its Own File
-
-One component per file, with the extracted child nested under its owner:
-
-```text
-src/features/nav/
-  menu/
-    index.ts                  # re-exports only menu.tsx
-    menu.tsx
-    menu-item.tsx             # exclusive child — imported directly by menu.tsx
-```
-
-```tsx
-// src/features/nav/menu/menu-item.tsx
-export function MenuItem({ label }: { label: string }): React.JSX.Element {
-  return <a href="#">{label}</a>;
-}
-```
-
-```tsx
-// src/features/nav/menu/menu.tsx
-import { MenuItem } from "./menu-item";
-import { locales } from "@/locales";
-
-export function Menu(): React.JSX.Element {
-  return (
-    <nav>
-      <MenuItem label={locales.nav.home} />
-      <MenuItem label={locales.nav.about} />
-    </nav>
-  );
-}
-```
-
-Why: `Menu` and `MenuItem` each have their own file, so both are independently searchable.

package/docs/code-organization-guide/rules/repeated-structure-rule.md

@@ -1,93 +0,0 @@
-# Repeated Structure Rule
-
-Repeated markup can drift when one copy changes and another does not. This rule makes repeated structure a clear extraction trigger.
-
-- A block of elements MUST be extracted as a named component when two or more places use the same arrangement of elements for the same purpose. Different data or labels do not prevent extraction.
-
-## Incorrect — Repeated Structure Kept Inline
-
-```tsx
-// src/features/dashboard/dashboard-view.tsx
-import { locales } from "@/locales";
-
-export function DashboardView({ stats, activity }: DashboardViewProps): React.JSX.Element {
-  return (
-    <main>
-      <section className="w-full rounded border p-6">
-        <h2>{locales.dashboard.stats}</h2>
-        <ul>
-          {stats.map((stat) => (
-            <li key={stat.id}>
-              {stat.label}: {stat.value}
-            </li>
-          ))}
-        </ul>
-      </section>
-
-      <section className="w-full rounded border p-6">
-        <h2>{locales.dashboard.recentActivity}</h2>
-        <ul>
-          {activity.map((event) => (
-            <li key={event.id}>
-              {event.label}: {event.value}
-            </li>
-          ))}
-        </ul>
-      </section>
-    </main>
-  );
-}
-```
-
-Why: the same section, heading, and list structure appears in two places. Changing the shared frame requires editing both copies.
-
-## Correct — Repeated Structure Extracted
-
-```text
-src/features/dashboard/
-  dashboard-view/
-    index.ts                  # re-exports only dashboard-view.tsx
-    dashboard-view.tsx
-    panel.tsx                 # exclusive child — imported directly
-```
-
-```tsx
-// src/features/dashboard/dashboard-view/panel.tsx
-type PanelItem = {
-  id: string;
-  label: string;
-  value: string | number;
-};
-
-export function Panel({ title, items }: { title: string; items: PanelItem[] }): React.JSX.Element {
-  return (
-    <section className="w-full rounded border p-6">
-      <h2>{title}</h2>
-      <ul>
-        {items.map((item) => (
-          <li key={item.id}>
-            {item.label}: {item.value}
-          </li>
-        ))}
-      </ul>
-    </section>
-  );
-}
-```
-
-```tsx
-// src/features/dashboard/dashboard-view/dashboard-view.tsx
-import { Panel } from "./panel";
-import { locales } from "@/locales";
-
-export function DashboardView({ stats, activity }: DashboardViewProps): React.JSX.Element {
-  return (
-    <main>
-      <Panel title={locales.dashboard.stats} items={stats} />
-      <Panel title={locales.dashboard.recentActivity} items={activity} />
-    </main>
-  );
-}
-```
-
-Why: `Panel` owns the shared section, heading, and list structure, while each call site supplies only its title and items.