pasika 0.1.6 → 0.2.0

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.

package/docs/code-organization-guide/rules/smart-vs-dumb-component-rule.md

@@ -1,112 +0,0 @@
-# Smart vs Dumb Component Rule
-
-Without a file-name convention, a component's smart vs dumb ownership is invisible to reviewers from the tree alone. Without a `data-testid` matching the file's casing, tests hardcode DOM identities that break on rename or restructure.
-
-- A smart component MUST fetch data, or define `handle*` callbacks and pass them to children as `on*` props.
-- A dumb component MUST NOT fetch data or define `handle*` callbacks for children.
-- A smart component file name MUST be `PascalCase.tsx`.
-- A dumb component file name MUST be `kebab-case.tsx`.
-- A smart component with one outer DOM element in every rendered result MUST set `data-testid` on that element, and its value MUST match the component name in `PascalCase`.
-- A smart component without one outer DOM element in every rendered result MAY omit `data-testid`.
-- A dumb component MAY set `data-testid` on its root element, and the value MUST be `kebab-case`.
-- [Next.js App Router routing files](https://nextjs.org/docs/app/getting-started/project-structure#routing-files) MUST use their required kebab-case names and are exempt from smart/dumb file-name and `data-testid` requirements.
-
-## Incorrect — Smart Component Uses a Dumb Name
-
-```tsx
-// src/features/social/social-stats-panel.tsx
-"use client";
-
-import { useSocialStats } from "./hooks/use-social-stats";
-import { PlatformCard } from "./platform-card";
-import { locales } from "@/locales";
-
-export function SocialStatsPanel(): React.JSX.Element {
-  const { stats, isLoading } = useSocialStats();
-
-  return (
-    <div data-testid="social-stats-panel">
-      {isLoading ? (
-        <p>{locales.social.loading}</p>
-      ) : (
-        stats.map((stat) => <PlatformCard key={stat.platform} data={stat} />)
-      )}
-    </div>
-  );
-}
-```
-
-Why: fetching data makes the component smart, but its file name and `data-testid` use dumb-component casing.
-
-## Correct — Smart Component Uses a Smart Name
-
-```tsx
-// src/features/social/SocialStatsPanel.tsx
-"use client";
-
-import { useSocialStats } from "./hooks/use-social-stats";
-import { PlatformCard } from "./platform-card";
-import { locales } from "@/locales";
-
-export function SocialStatsPanel(): React.JSX.Element {
-  const { stats, isLoading } = useSocialStats();
-
-  return (
-    <div data-testid="SocialStatsPanel">
-      {isLoading ? (
-        <p>{locales.social.loading}</p>
-      ) : (
-        stats.map((stat) => <PlatformCard key={stat.platform} data={stat} />)
-      )}
-    </div>
-  );
-}
-```
-
-Why: fetching data makes the component smart, so its file name and `data-testid` use `PascalCase`.
-
-## Incorrect — Dumb Component Uses a Smart Name
-
-```tsx
-// src/features/social/PlatformCard.tsx
-
-export function PlatformCard({
-  data,
-  onFollowClick,
-}: {
-  data: PlatformStat;
-  onFollowClick: () => void;
-}): React.JSX.Element {
-  return (
-    <article data-testid="PlatformCard">
-      <h3>{data.platform}</h3>
-      <FollowButton onFollowClick={onFollowClick} />
-    </article>
-  );
-}
-```
-
-Why: the component fetches no data and only receives a child callback, so it is dumb. Its file name and `data-testid` use smart-component casing.
-
-## Correct — Dumb Component Uses a Dumb Name
-
-```tsx
-// src/features/social/platform-card.tsx
-
-export function PlatformCard({
-  data,
-  onFollowClick,
-}: {
-  data: PlatformStat;
-  onFollowClick: () => void;
-}): React.JSX.Element {
-  return (
-    <article data-testid="platform-card">
-      <h3>{data.platform}</h3>
-      <FollowButton onFollowClick={onFollowClick} />
-    </article>
-  );
-}
-```
-
-Why: the component is dumb, so its file name and `data-testid` use `kebab-case`.

package/docs/code-organization-guide/rules/sole-state-owner-rule.md

@@ -1,101 +0,0 @@
-# Sole State Owner Rule
-
-Some blocks of elements are the only consumers of a state hook. This rule extracts those blocks into components that own the hook.
-
-- A component MUST extract a named component when one part of its JSX contains every JSX expression, callback, and effect that reads one state hook's value or calls its updater.
-
-## Incorrect — Parent Keeps Child-Only State
-
-```tsx
-// src/compositions/dashboard-view.tsx
-import { locales } from "@/locales";
-
-export function DashboardView(): React.JSX.Element {
-  const [isHelpOpen, setIsHelpOpen] = useState(false);
-
-  return (
-    <div>
-      <h1>{locales.dashboard}</h1>
-      <button onClick={() => setIsHelpOpen(true)} type="button">
-        {locales.help}
-      </button>
-      {isHelpOpen && (
-        <Modal onClose={() => setIsHelpOpen(false)}>
-          <HelpContent />
-        </Modal>
-      )}
-      <DashboardContent />
-    </div>
-  );
-}
-```
-
-Why: the help button and modal are the only users of `isHelpOpen`, but the state lives in `DashboardView`.
-
-## Correct — Child Owns Its State
-
-```text
-src/compositions/
-  dashboard-view/
-    index.ts                  # re-exports only dashboard-view.tsx
-    dashboard-view.tsx
-    help-dialog/
-      index.ts                # re-exports only help-dialog.tsx
-      help-dialog.tsx
-      help-trigger.tsx        # exclusive child — imported directly
-```
-
-```tsx
-// src/compositions/dashboard-view/help-dialog/help-dialog.tsx
-import { HelpTrigger } from "./help-trigger";
-
-export function HelpDialog(): React.JSX.Element {
-  const [isHelpOpen, setIsHelpOpen] = useState(false);
-
-  return (
-    <>
-      <HelpTrigger onOpen={() => setIsHelpOpen(true)} />
-      {isHelpOpen && (
-        <Modal onClose={() => setIsHelpOpen(false)}>
-          <HelpContent />
-        </Modal>
-      )}
-    </>
-  );
-}
-```
-
-```tsx
-// src/compositions/dashboard-view/help-dialog/help-trigger.tsx
-import { locales } from "@/locales";
-
-type HelpTriggerProps = {
-  onOpen: () => void;
-};
-
-export function HelpTrigger({ onOpen }: HelpTriggerProps): React.JSX.Element {
-  return (
-    <button onClick={onOpen} type="button">
-      {locales.help}
-    </button>
-  );
-}
-```
-
-```tsx
-// src/compositions/dashboard-view/dashboard-view.tsx
-import { HelpDialog } from "./help-dialog";
-import { locales } from "@/locales";
-
-export function DashboardView(): React.JSX.Element {
-  return (
-    <div>
-      <h1>{locales.dashboard}</h1>
-      <HelpDialog />
-      <DashboardContent />
-    </div>
-  );
-}
-```
-
-Why: `HelpDialog` owns the help button, modal, and `isHelpOpen` state. `DashboardView` only composes it.

package/docs/code-organization-guide/rules/types-and-schemas-rule.md

@@ -1,139 +0,0 @@
-# Types and Schemas Rule
-
-Types and schemas are easy to bury in component files or scatter across the project. This rule keeps them close to one component and gives independently used ones a consistent location.
-
-- A type or schema declared in a component MUST stay in that component file until another file imports it without the component where it is defined.
-- Importing a type or schema alongside the component that defines it MUST NOT require extraction.
-- A type or schema declared outside a component MUST stay in its file until another file needs it without using the code in that file.
-- Extracted types and schemas MUST live in their matching `types/` or `schemas/` folder at the closest common folder (CCF) of their consumers.
-- When a type or schema's CCF is `src/features/`, it MUST move to `src/types/` or `src/schemas/`.
-- A `types/` or `schemas/` folder MUST either define its exports directly in `index.ts` or group related types and schemas in kebab-case files that `index.ts` named-re-exports.
-- Consumers MUST import an extracted type or schema through the `index.ts` in that type or schema's `types/` or `schemas/` folder.
-- A type or schema used only to implement one configuration module MUST live in that module's `types/` or `schemas/` folder.
-- A type MAY stay in `src/config/<module>/` when its meaning is derived from the configuration that it parameterizes, even when consumers exist outside the config module.
-
-## Incorrect — Feature and Composition Type Kept in a Feature
-
-```text
-src/
-├── compositions/
-│   └── BillingDashboard.tsx
-├── features/
-│   └── billing/
-│       ├── invoice.tsx
-│       └── types/
-│           ├── billing.ts
-│           └── index.ts
-```
-
-```tsx
-// src/features/billing/invoice.tsx
-import type { InvoiceStatus } from "./types";
-
-// src/compositions/BillingDashboard.tsx
-import type { InvoiceStatus } from "@/features/billing/types";
-```
-
-Why: the feature and composition have `src/` as their CCF, but the type remains in the billing feature.
-
-## Correct — Feature and Composition Type in `src/types/`
-
-```text
-src/
-├── compositions/
-│   └── BillingDashboard.tsx
-├── features/
-│   └── billing/
-│       └── invoice.tsx
-└── types/
-    ├── billing.ts
-    └── index.ts
-```
-
-```ts
-// src/types/billing.ts
-export type InvoiceStatus = "draft" | "paid";
-export type PaymentMethod = "card" | "bank";
-
-// src/types/index.ts
-export type { InvoiceStatus, PaymentMethod } from "./billing";
-```
-
-```tsx
-// src/features/billing/invoice.tsx
-import type { InvoiceStatus } from "@/types";
-
-// src/compositions/BillingDashboard.tsx
-import type { InvoiceStatus } from "@/types";
-```
-
-Why: the feature and composition have `src/` as their CCF, so the type lives in `src/types/`.
-
-## Incorrect — Type Imported Independently from a Component
-
-```tsx
-// src/features/billing/invoice.tsx
-export type DateRange = { from: Date; to: Date };
-
-export function Invoice({ range }: { range: DateRange }): React.JSX.Element {
-  return <InvoiceView range={range} />;
-}
-```
-
-```ts
-// src/features/billing/hooks/use-billing-filter.ts
-import type { DateRange } from "../invoice";
-```
-
-Why: the hook reaches into a component file for a type it uses independently.
-
-## Correct — Independently Used Type Extracted
-
-```ts
-// src/features/billing/types/index.ts
-export type DateRange = { from: Date; to: Date };
-
-// src/features/billing/hooks/use-billing-filter.ts
-import { type DateRange } from "../types";
-```
-
-Why: the component and hook can use the billing feature's types index independently.
-
-## Incorrect — Schema Imported Independently from a Component
-
-```tsx
-// src/features/billing/invoice-form.tsx
-import { z } from "zod";
-
-export const invoiceSchema = z.object({
-  amount: z.number().positive(),
-});
-```
-
-```ts
-// src/features/billing/hooks/use-invoice-draft.ts
-import { invoiceSchema } from "../invoice-form";
-```
-
-Why: the hook reaches into a component file for a schema it uses independently.
-
-## Correct — Independently Used Schema Extracted
-
-```ts
-// src/features/billing/schemas/index.ts
-import { z } from "zod";
-
-export const invoiceSchema = z.object({
-  amount: z.number().positive(),
-});
-```
-
-```tsx
-// src/features/billing/invoice-form.tsx
-import { invoiceSchema } from "./schemas";
-
-// src/features/billing/hooks/use-invoice-draft.ts
-import { invoiceSchema } from "../schemas";
-```
-
-Why: the component and hook can use the billing feature's schemas index independently.

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

@@ -1,86 +0,0 @@
-# Utilities Rule
-
-Pure functions should not be hidden in component files. This rule extracts them to a predictable `utils/` folder and keeps their imports direct.
-
-- A pure function MUST be extracted to `utils/`, even when it has one consumer.
-- An extracted utility MUST live in the `utils/` folder at the closest common folder (CCF) of its consumers.
-- When a utility's CCF is `src/features/`, it MUST move to `src/utils/`.
-- A utility MUST be imported directly without a barrel.
-- A utility file that exports one function MUST have a name in that function's kebab-case form.
-- Utilities that are used together MAY be grouped in a file with a kebab-case name.
-- A utility used only to implement one configuration module MUST live in that module's `utils/` folder.
-
-## Incorrect — Pure Function Left Beside Its Consumer
-
-```tsx
-// src/features/billing/invoice.tsx
-const calculateInvoiceTotal = (items: InvoiceItem[]): number => {
-  return items.reduce((total, item) => total + item.amount, 0);
-};
-
-export function Invoice({ items }: InvoiceProps): React.JSX.Element {
-  const total = calculateInvoiceTotal(items);
-  return <InvoiceTotal value={total} />;
-}
-```
-
-Why: the pure function is mixed into a component file.
-
-## Correct — Pure Function in a Directly Imported Utility File
-
-```ts
-// src/features/billing/utils/calculate-invoice-total.ts
-export function calculateInvoiceTotal(items: InvoiceItem[]): number {
-  return items.reduce((total, item) => total + item.amount, 0);
-}
-```
-
-```tsx
-// src/features/billing/invoice.tsx
-import { calculateInvoiceTotal } from "./utils/calculate-invoice-total";
-
-export function Invoice({ items }: InvoiceProps): React.JSX.Element {
-  const total = calculateInvoiceTotal(items);
-  return <InvoiceTotal value={total} />;
-}
-```
-
-Why: the function has a focused utility file in the billing feature's `utils/` folder.
-
-## Incorrect — Shared Utility Kept in a Feature
-
-```ts
-// src/features/billing/utils/format-retry-delay.ts
-export function formatRetryDelay(milliseconds: number): string {
-  return `${milliseconds / 1000} seconds`;
-}
-```
-
-```tsx
-// src/features/billing/invoice.tsx
-import { formatRetryDelay } from "./utils/format-retry-delay";
-
-// src/compositions/billing-dashboard.tsx
-import { formatRetryDelay } from "@/features/billing/utils/format-retry-delay";
-```
-
-Why: the utility is imported by both a feature and a composition, so it cannot stay in the billing feature.
-
-## Correct — Shared Utility in `src/utils/`
-
-```ts
-// src/utils/format-retry-delay.ts
-export function formatRetryDelay(milliseconds: number): string {
-  return `${milliseconds / 1000} seconds`;
-}
-```
-
-```tsx
-// src/features/billing/invoice.tsx
-import { formatRetryDelay } from "@/utils/format-retry-delay";
-
-// src/compositions/billing-dashboard.tsx
-import { formatRetryDelay } from "@/utils/format-retry-delay";
-```
-
-Why: the utility's CCF is `src/`, so it lives in `src/utils/`.

package/docs/documentation-guide/_templates/grouped-reference.md

@@ -1,11 +0,0 @@
-# [Topic] Reference
-
-[1-2 short sentences naming exactly what readers can look up here and when they should use this reference.]
-
-## [Lookup Block Name]
-
-[1-2 short sentences explaining what this lookup block contains and why it is included.]
-
-[Place this lookup block's content here.]
-
-[Repeat this section for every remaining lookup block.]

package/docs/documentation-guide/_templates/guide.md

@@ -1,19 +0,0 @@
-# [Topic] Guide
-
-[1-2 short descriptive sentences explaining this guide's scope, underlying idea, and why it matters.]
-
-## How To [Workflow]
-
-[What does this accomplish? When should it run?]
-
-1. [Step 1]
-2. [Step 2]
-
-## How To [Another Workflow]
-
-[What does this accomplish? When should it run?]
-
-1. [Step 1]
-2. [Step 2]
-
-[Repeat this section only when the guide has another real workflow. Otherwise delete it.]

package/docs/documentation-guide/_templates/rule.md

@@ -1,21 +0,0 @@
-# [Rule Name] Rule
-
-[What problem does this rule solve?]
-
-- [Requirement using MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY]
-
-## Incorrect — [Concise example description]
-
-```[lang]
-// code
-```
-
-Why: [What makes this incorrect?]
-
-## Correct — [Concise example description]
-
-```[lang]
-// code
-```
-
-Why: [What makes this correct?]

package/docs/documentation-guide/_templates/single-lookup-reference.md

@@ -1,5 +0,0 @@
-# [Topic] Reference
-
-[1-2 short sentences naming exactly what readers can look up here and when they should use this reference.]
-
-[Place the reference's single lookup block here without a heading.]

package/docs/documentation-guide/documentation-guide.md

@@ -1,13 +0,0 @@
-# Documentation Guide
-
-This guide explains how to create Rules, References, and Guides in this repository.
-
-## How To Create a Document
-
-Run this whenever you add a new doc to the repository.
-
-1. Pick the document kind from the [Documentation Types Reference](references/documentation-types-reference.md) so you know the right template.
-2. Follow the [Template Usage Rule](rules/template-usage-rule.md) so the doc has no leftover bracketed prompts.
-3. For a Guide, follow the [Guide Creation Rule](rules/guide-creation-rule.md) so the doc has the correct shape, naming, and folder layout.
-4. For a Rule, follow the [Rule Creation Rule](rules/rule-creation-rule.md) so the doc has the correct shape, naming, and vocabulary.
-5. For a Reference, follow the [Reference Creation Rule](rules/reference-creation-rule.md) so the doc has the correct shape, naming, and folder layout.

package/docs/documentation-guide/references/documentation-types-reference.md

@@ -1,9 +0,0 @@
-# Documentation Types Reference
-
-Use this reference to look up the three standard Markdown document kinds in this repository.
-
-| Kind      | Shape                                                                                           | Template                                                              |
-| --------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Guide     | A workflow-oriented document with one or more `## How To [...]` sections.                       | `/_templates/guide.md`                                                |
-| Rule      | An opinionated project rule that states required, forbidden, recommended, or optional behavior. | `/_templates/rule.md`                                                 |
-| Reference | Lookup material. A lookup block is one self-contained set of facts for a reader's question. Use the single template for one lookup block and the grouped template for several blocks organized by topic. | `/_templates/single-lookup-reference.md` or `/_templates/grouped-reference.md` |