pasika 0.1.4 → 0.2.0

package/docs/code-organization-guide/rules/native-prop-forwarding-rule.md

@@ -1,38 +0,0 @@
-# Native Prop Forwarding Rule
-
-When a `src/shared/` component renders the same intrinsic root element in every rendered result, a smaller custom prop interface can hide capabilities that consumers need. This rule preserves native props while allowing focused component-specific props.
-
-- A `src/shared/` component with the same intrinsic root element in every rendered result MUST include that element's native props in its props type.
-- A `src/shared/` component with the same intrinsic root element in every rendered result MUST forward unconsumed native props to that element.
-- A `src/shared/` component with the same intrinsic root element in every rendered result MAY add component-specific props alongside its native props.
-
-## Incorrect — Native Props Replaced
-
-```tsx
-// src/shared/button.tsx
-type ButtonProps = {
-  label: string;
-  onClick(): void;
-};
-
-export function Button({ label, onClick }: ButtonProps) {
-  return <button onClick={onClick}>{label}</button>;
-}
-```
-
-Why: the custom interface leaves out native button props such as `disabled`, `type`, and accessible labels.
-
-## Correct — Native Props Extended and Forwarded
-
-```tsx
-// src/shared/button.tsx
-type ButtonProps = React.ComponentProps<"button"> & {
-  loading?: boolean;
-};
-
-export function Button({ className, loading, disabled, ...props }: ButtonProps) {
-  return <button className={cn("inline-flex items-center", className)} disabled={disabled || loading} {...props} />;
-}
-```
-
-Why: the component forwards its unused native props while adding the `loading` state it needs.

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

@@ -1,64 +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.
-- A non-component module MUST use `.ts`, except when a framework requires a `.tsx` routing file.
-
-## 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 the same structural frame and semantic purpose appear in two or more places. 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,116 +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.
-
-- Remote or shared application data or state is data from a server, context, store, URL, or server action. A component MUST be smart when it fetches or mutates that data, performs an effect, or defines a callback that changes it, including through a hook or service.
-- A component is considered to perform these operations when it calls a custom hook that performs them.
-- In this rule, an effect MUST be a subscription, external I/O, DOM manipulation, or resource lifecycle.
-- Local UI state and callbacks that only update it MUST NOT make a component smart, including when passed to another component or directly to a native element.
-- A dumb component MUST NOT do any of these.
-- A component that does none of these MUST be dumb.
-- 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,102 +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 state hook's consumers are the JSX, callbacks, and effects that read its state value or call its updater.
-- A proper sub-block of a component's output MUST be extracted when it contains every consumer of one state hook and one clear component name describes it. A consumer declared before `return` belongs to a sub-block only when it is used exclusively by that sub-block; otherwise this rule does not require extraction. The component that owns the state is not itself an extraction trigger.
-
-## 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,138 +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 used only to implement one configuration object MUST live in that object's `types/` or `schemas/` folder.
-- Except for a type or schema used only to implement one configuration object, 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 it alongside that component does not trigger extraction.
-- Except for a type or schema used only to implement one configuration object, a type or schema declared outside a component MUST stay with its declaring module until another file imports it independently.
-- Extracted types and schemas MUST live in their matching `types/` or `schemas/` folder at the closest common folder (CCF) of their consumers.
-- A `types/` or `schemas/` `index.ts` MAY define its exports directly.
-- Types and schemas that are used together MAY be grouped in a file with a kebab-case name and named-re-exported from `index.ts`.
-- When a `types/` or `schemas/` folder uses grouped files, its `index.ts` MUST only named-re-export those files.
-- When a type or schema's CCF is `src/features/`, it MUST move to `src/types/` or `src/schemas/`.
-
-## 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,87 +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.
-- A pure function returns the same result for the same arguments and does not read or write external mutable state, perform I/O, or manipulate the DOM.
-- A utility used only to implement one configuration object MUST live in that object's `utils/` folder.
-- 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.
-
-## 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/guide.md

@@ -1,19 +0,0 @@
-# [Topic] Guide
-
-[1-2 short sentences explaining the underlying idea behind this guide 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/reference.md

@@ -1,17 +0,0 @@
-# [Topic] Reference
-
-[1-2 short sentences naming exactly what readers can look up here and when they should use this reference.]
-
-[Single lookup content — table, glossary, hierarchy, catalog, or config block. Keep this branch only when the reference has exactly one lookup block; it has no section heading. Otherwise delete this branch and use one heading per lookup group below.]
-
-## [First Lookup Group Name]
-
-[1-2 short sentences explaining what this group contains and why it is included.]
-
-[Place this group's lookup content here.]
-
-## [Next Lookup Group Name]
-
-[1-2 short sentences explaining what this group contains and why it is included.]
-
-[Place this group's lookup content here. Repeat the heading, explanation, and lookup content for every remaining group; delete this multi-block branch when the reference has one lookup block.]