pasika 0.1.6 → 0.3.0

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` |

package/docs/documentation-guide/rules/guide-creation-rule.md

@@ -1,113 +0,0 @@
-# Guide Creation Rule
-
-Guides without a consistent creation process invent their own structure. This rule defines how to create a Guide document.
-
-- Each How To step MUST be concise and use one sentence.
-- A Guide MAY reference Rules, References, and other Guides.
-- A Guide overview MUST contain one or two short descriptive sentences about the guide's scope and purpose, and MUST NOT contain instructions or links to other documentation.
-- Each How To step MUST link at most one documentation file total, whether that file is a Rule, Reference, or Guide.
-- When a step links a Rule, Reference, or Guide, the step MUST name the concrete decision or result the reader will have after reading it.
-- A step that links another Guide MUST link directly to the relevant How To section.
-- How To sections MUST NOT nest inside other How To sections.
-- Guide file names MUST match the document title in kebab-case and use the `-guide` suffix (e.g., `foo-guide.md`).
-- A Guide with private support files MUST become a folder named the same as its entry-point file, without the `.md` extension.
-- Private Rule files for a Guide MUST live in a `rules/` subfolder inside the Guide's folder.
-- Private Reference files for a Guide MUST live in a `references/` subfolder inside the Guide's folder.
-
-## Incorrect — Private Documents Mixed at the Guide Root
-
-```text
-feature-workflow-guide/
-├── feature-workflow-guide.md
-├── naming-rule.md
-└── option-reference.md
-```
-
-Why: mixed Markdown files turn the doc folder into an undifferentiated list once the doc grows.
-
-## Correct — Private Documents Grouped by Kind
-
-```text
-feature-workflow-guide/
-├── feature-workflow-guide.md
-├── rules/
-│   └── naming-rule.md
-└── references/
-    └── option-reference.md
-```
-
-Why: private support files stay colocated with the entry point while being grouped by document kind.
-
-## Incorrect — Step Links to Multiple Documents
-
-```markdown
-1. Follow the [Naming Rule](rules/naming-rule.md) and the [Layout Rule](rules/layout-rule.md) so the doc looks right.
-```
-
-Why: step links two Rules and does not name a concrete decision or result.
-
-## Correct — Step Links to One Document
-
-```markdown
-1. Follow the [Naming Rule](rules/naming-rule.md) so the doc has a predictable file name.
-```
-
-Why: step links one Rule and names the concrete result the reader will have.
-
-## Incorrect — Nested How To Section
-
-```markdown
-## How To Deploy
-
-1. Build the project.
-   ### How To Build
-   1. Run the build script.
-```
-
-Why: a How To section nests inside a step of another How To section.
-
-## Correct — Flat How To Sections
-
-```markdown
-## How To Deploy
-
-1. Follow [How To Build](#how-to-build) to build the project.
-
-## How To Build
-
-1. Run the build script.
-```
-
-Why: How To sections stay flat and reference each other via links.
-
-## Incorrect — Multi-Sentence Step
-
-```markdown
-1. First, check the configuration file. Then verify all required fields are present. After that, confirm none of the fields contain invalid values.
-```
-
-Why: step uses multiple sentences instead of one concise sentence.
-
-## Correct — Concise Step
-
-```markdown
-1. Run the config check script.
-```
-
-Why: step is one concise sentence with a concrete action.
-
-## Incorrect — Guide Link Omits Its How To Section
-
-```markdown
-1. Follow the [Build Guide](build-guide.md) to build the project.
-```
-
-Why: link points at a Guide file but does not anchor to a specific How To section, so the reader lands on the guide's introduction and has to search for the relevant workflow.
-
-## Correct — Guide Link Targets Its How To Section
-
-```markdown
-1. Follow [How To Build](build-guide.md#how-to-build) to build the project.
-```
-
-Why: link anchors to the specific How To section, so the reader lands directly on the relevant workflow.