pasika 0.1.0 → 0.1.4

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

@@ -0,0 +1,68 @@
+# 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 at most one logical operator, one ternary, or one built-in method call. `cn()` is an explicit exception to the external-function-call restriction. Calls inside an event-handler callback are not JSX expressions.
+
+## 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);
+const daysAgoLabel = locales.daysAgo;
+
+let statusView = <Content />;
+if (isLoading) {
+  statusView = <Spinner />;
+} else if (hasError) {
+  statusView = <Error />;
+}
+
+return (
+  <div>
+    <span>{daysSinceUpdate} {daysAgoLabel}</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

@@ -0,0 +1,55 @@
+# 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`.
+- A locale consumer is a module that reads the locale.
+- A new locale with no consumers MUST use a feature namespace when it is for one feature; otherwise it MUST live at the top level of `locales`.
+- Locales read only by modules 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 modules 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

@@ -0,0 +1,66 @@
+# 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/native-prop-forwarding-rule.md

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,64 @@
+# 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

@@ -0,0 +1,93 @@
+# 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

@@ -0,0 +1,116 @@
+# 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

@@ -0,0 +1,102 @@
+# 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.