@starci/hfs 4.9.5 → 4.9.8

package/templates/fe/units/leaf/index.tsx.tpl

@@ -0,0 +1,10 @@
+import { Badge } from "@starci/grammar/common"
+
+/** One resolved label and the waiting flag of the block that draws it. */
+type {{Name}}Props = {
+    readonly label: string
+    readonly isSkeleton: boolean
+}
+
+/** A fixed semantic unit over one Grammar leaf; it rests as itself by passing `isSkeleton` on. */
+export const {{Name}} = (props: {{Name}}Props) => <Badge isSkeleton={props.isSkeleton}>{props.label}</Badge>

package/templates/fe/units/overlay/component.tsx.tpl

@@ -0,0 +1,27 @@
+import { {{grammarImports}} } from "@starci/grammar/common"
+
+/** The copy, the open state and the actions the connected {{Name}} supplies; atoms only. */
+export interface {{Name}}BaseProps {
+    readonly props: {
+        readonly isOpen: boolean
+        readonly triggerLabel: string
+        readonly title: string
+{{labelMembers}}        readonly cancelLabel: string
+        readonly submitLabel: string
+    }
+    readonly on: {
+        readonly openChange: (isOpen: boolean) => void
+{{submitMember}}    }
+}
+
+/** {{doc}} */
+export const {{Name}}Base = (props: {{Name}}BaseProps) => (
+    <{{shell}}
+        isOpen={props.props.isOpen}
+        onOpenChange={props.on.openChange}
+        title={props.props.title}
+{{shellAttributes}}        trigger={<Button intent="neutral">{props.props.triggerLabel}</Button>}
+{{footer}}    >
+{{body}}
+    </{{shell}}>
+)

package/templates/fe/units/overlay/index.tsx.tpl

@@ -0,0 +1,23 @@
+"use client"
+
+import { useState } from "react"
+import { useTranslations } from "next-intl"
+import { {{Name}}Base } from "./component"
+
+/** The connected {{Name}}: owns whether it is open, resolves every label and renders its pure half. */
+export const {{Name}} = () => {
+    const t = useTranslations("{{nameCamel}}")
+    const [isOpen, setIsOpen] = useState(false)
+    return (
+        <{{Name}}Base
+            props={{
+                isOpen,
+                triggerLabel: t("open"),
+                title: t("title"),
+{{labelsResolved}}                cancelLabel: t("cancel"),
+                submitLabel: t("submit"),
+            }}
+            on={{ openChange: setIsOpen, {{submitHandler}} }}
+        />
+    )
+}

package/templates/fe/units/overlay/stories.tsx.tpl

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react-vite"
+import { {{Name}}Base } from "../../src/features/overlays/{{Name}}/component"
+import type { {{Name}}BaseProps } from "../../src/features/overlays/{{Name}}/component"
+
+/** The copy of the overlay. */
+const COPY: {{Name}}BaseProps["props"] = {
+    isOpen: false,
+    triggerLabel: "Open",
+    title: "{{title}}",
+{{labelsFixture}}    cancelLabel: "Cancel",
+    submitLabel: "Save",
+}
+
+/** The pure half of {{Name}}: closed behind its trigger, and open. */
+const meta = {
+    title: "{{Name}}",
+    component: {{Name}}Base,
+    args: { props: COPY, on: { openChange: () => undefined, {{submitFixture}} } },
+} satisfies Meta<typeof {{Name}}Base>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/** Closed: only its trigger shows. */
+export const Closed: Story = {}
+
+/** Open above the page. */
+export const Open: Story = { args: { props: { ...COPY, isOpen: true } } }

package/templates/fe/units/page/component.tsx.tpl

@@ -0,0 +1,35 @@
+import { {{grammarImports}} } from "@starci/grammar/common"
+{{blockImports}}
+/** The copy of {{Name}} and whether its subject is still unresolved, supplied by the page owner. */
+export interface {{Name}}BaseProps {
+    readonly props: {
+        readonly title: string
+        readonly breadcrumbLabel: string
+        readonly homeLabel: string
+        readonly homeHref: string
+{{emptyMember}}{{tabsMember}}        /** True for the route's loading view: the same page, its header resting in its own boxes (STATE-8). */
+        readonly isSkeleton: boolean
+    }
+}
+
+/**
+ * Draws {{Name}} as one Grammar Page (R325): the header band carries the trail and the heading, and page commands go to
+ * `header.actions`, page views to `header.tabs` (R324); the body composes the page's blocks, each owning its own data and loading.
+ */
+export const {{Name}}Base = (props: {{Name}}BaseProps) => (
+    <Page
+        header={{
+            title: props.props.title,
+            breadcrumbs: {
+                label: props.props.breadcrumbLabel,
+                items: [
+                    { id: "home", label: props.props.homeLabel, href: props.props.homeHref },
+                    { id: "{{routeId}}", label: props.props.title },
+                ],
+            },
+{{tabsHeader}}        }}
+        isSkeleton={props.props.isSkeleton}
+    >
+{{body}}
+    </Page>
+)

package/templates/fe/units/page/error-component.tsx.tpl

@@ -0,0 +1,18 @@
+import { Alert, Page } from "@starci/grammar/common"
+
+/** The copy of the {{route}} route's failure and the retry its boundary hands over. */
+export interface {{ErrorName}}BaseProps {
+    readonly props: {
+        readonly title: string
+        readonly message: string
+        readonly retryLabel: string
+    }
+    readonly on: { readonly retry: () => void }
+}
+
+/** A failed {{route}} route keeps its page and puts one negative Alert where the first region would be (STATE-8). */
+export const {{ErrorName}}Base = (props: {{ErrorName}}BaseProps) => (
+    <Page header={{ title: props.props.title }}>
+        <Alert title={props.props.message} tone="negative" action={{ label: props.props.retryLabel, onAction: props.on.retry }} />
+    </Page>
+)

package/templates/fe/units/page/error-index.tsx.tpl

@@ -0,0 +1,11 @@
+import { useTranslations } from "next-intl"
+import { {{ErrorName}}Base } from "./component"
+
+/** The public props of the {{route}} error page: the boundary hands it the retry. */
+type {{ErrorName}}Props = { readonly onRetry: () => void }
+
+/** A render failure under the {{route}} route shows this page instead of a blank one; retry renders the segment again. */
+export const {{ErrorName}} = (props: {{ErrorName}}Props) => {
+    const t = useTranslations("{{nameCamel}}")
+    return <{{ErrorName}}Base props={{ title: t("title"), message: t("failed"), retryLabel: t("retry") }} on={{ retry: props.onRetry }} />
+}

package/templates/fe/units/page/index.tsx.tpl

@@ -0,0 +1,29 @@
+import type { Metadata } from "next"
+import { getTranslations } from "next-intl/server"
+import { APP_ROUTES } from "@/modules/routes"
+import { {{Name}}Base } from "./component"
+import type { {{Name}}BaseProps } from "./component"
+
+/** The document title of {{Name}}, from the catalog of the requested locale. */
+export const {{nameCamel}}Metadata = async (): Promise<Metadata> => {
+    const t = await getTranslations("{{nameCamel}}")
+    return { title: t("title") }
+}
+
+/** The copy of {{Name}}, resolved once on the server for the page and for its loading view. */
+const copyOf = async (isSkeleton: boolean): Promise<{{Name}}BaseProps["props"]> => {
+    const t = await getTranslations("{{nameCamel}}")
+    return {
+        title: t("title"),
+        breadcrumbLabel: t("breadcrumb"),
+        homeLabel: t("home"),
+        homeHref: APP_ROUTES.home,
+{{emptyResolved}}{{tabsResolved}}        isSkeleton,
+    }
+}
+
+/** The {{route}} page: a server owner that resolves its copy and composes its blocks; it reads no data. */
+export const {{Name}} = async () => <{{Name}}Base props={await copyOf(false)} />
+
+/** The {{route}} route's loading view: the same page drawn in skeleton mode, never a separate layout (STATE-8). */
+export const {{LoadingName}} = async () => <{{Name}}Base props={await copyOf(true)} />

package/templates/fe/units/page/route-error.tsx.tpl

@@ -0,0 +1,10 @@
+"use client"
+
+import { {{ErrorName}} } from "@/features/pages/{{ErrorName}}"
+
+type ErrorProps = { readonly reset: () => void }
+
+/** The {{route}} route's error boundary slot: it mounts the route's error page and hands it the segment's retry. */
+const ErrorBoundary = (props: ErrorProps) => <{{ErrorName}} onRetry={props.reset} />
+
+export default ErrorBoundary

package/templates/fe/units/page/route-loading.tsx.tpl

@@ -0,0 +1,6 @@
+import { {{LoadingName}} } from "@/features/pages/{{Name}}"
+
+/** The {{route}} route's loading slot: it mounts the page in skeleton mode and nothing else. */
+const Loading = () => <{{LoadingName}} />
+
+export default Loading

package/templates/fe/units/page/route-page.tsx.tpl

@@ -0,0 +1,9 @@
+import { {{Name}} } from "@/features/pages/{{Name}}"
+
+/** The document title of this page, from the catalog of the requested locale. */
+export { {{nameCamel}}Metadata as generateMetadata } from "@/features/pages/{{Name}}"
+
+/** The {{route}} route's page slot: it mounts {{Name}} and nothing else. */
+const Page = () => <{{Name}} />
+
+export default Page

package/templates/fe/units/page/stories.tsx.tpl

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from "@storybook/react-vite"
+import { {{Name}}Base } from "../../src/features/pages/{{Name}}/component"
+import type { {{Name}}BaseProps } from "../../src/features/pages/{{Name}}/component"
+
+/** The copy of the resolved page. */
+const READY: {{Name}}BaseProps["props"] = {
+    title: "{{title}}",
+    breadcrumbLabel: "Breadcrumb",
+    homeLabel: "Home",
+    homeHref: "/",
+{{emptyFixture}}{{tabsFixture}}    isSkeleton: false,
+}
+
+/** The pure half of {{Name}}: the resolved page and its loading view, paired for the DNA gate. */
+const meta = {
+    title: "{{Name}}",
+    component: {{Name}}Base,
+    args: { props: READY },
+} satisfies Meta<typeof {{Name}}Base>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/** The resolved page. */
+export const Ready: Story = {
+    parameters: { dna: { pair: "Ready", phase: "ready" } },
+}
+
+/** The route's loading view: the same page, its header resting in its own boxes. */
+export const ReadySkeleton: Story = {
+    args: { props: { ...READY, isSkeleton: true } },
+    parameters: { dna: { pair: "Ready", phase: "loading" } },
+}

package/templates/fe/units/slot/SlotView.tsx.tpl

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react"
+import { EmptyNotice } from "@starci/grammar/common"
+{{slotTypes}}
+/** One region's read, its same-shape placeholder, its resolved status copy and the ready tree it draws. */
+type SlotViewProps<T> = {
+    readonly slot: DataSlot<T>
+    /** A value of the same shape as the items: while loading, the ready tree draws it with `isSkeleton`. */
+    readonly placeholder: T
+    readonly labels: SlotLabels
+    /** A primary region says it is forbidden in place; a secondary one disappears. */
+    readonly forbidden?: "notice" | "hide"
+    /** Re-runs exactly the read of this slot. */
+    readonly onRetry: () => void
+    readonly children: (items: T, isSkeleton: boolean) => ReactNode
+}
+
+/** The one status view (FE-ERROR-1): every region renders its loading, forbidden, error and empty status through here. */
+export const SlotView = <T,>(props: SlotViewProps<T>) => {
+    if (props.slot.isLoading === true) return props.children(props.placeholder, true)
+    if (props.slot.isForbidden === true) return props.forbidden === "hide" ? null : <EmptyNotice message={props.labels.forbidden} />
+    if (props.slot.isError === true) {
+        return <EmptyNotice message={props.labels.error} actionLabel={props.labels.retry} onAction={props.onRetry} />
+    }
+    const items = props.slot.items
+    // No items, or an empty list, is the region's empty sentence.
+    if (items === undefined || (Array.isArray(items) && items.length === 0)) return <EmptyNotice message={props.labels.empty} />
+    return props.children(items, false)
+}

package/templates/fe/units/slot/data-slot.ts.tpl

@@ -0,0 +1,18 @@
+/**
+ * The data status of one read (FE-ERROR-1). Every field is an atom, so a slot crosses into a pure half; a region with
+ * two reads carries two slots, and each one shows its own status. No flag set and no items means empty.
+ */
+export interface DataSlot<T> {
+    readonly items: T | undefined
+    readonly isLoading?: boolean
+    readonly isError?: boolean
+    readonly isForbidden?: boolean
+}
+
+/** The resolved copy of the status view for one slot: the shared status sentences plus the region's own empty sentence. */
+export interface SlotLabels {
+    readonly empty: string
+    readonly forbidden: string
+    readonly error: string
+    readonly retry: string
+}

package/templates/fe/units/slot/slot.shared.ts.tpl

@@ -0,0 +1,35 @@
+import type { DataSlot } from "@/modules/types"
+
+/**
+ * The part of an operation's GraphQLResponse a slot reads: whether it succeeded, its value and the refusal kind. Only hooks/swr
+ * imports an operation's types, so the slot owner reads the outcome by these fields alone.
+ */
+interface SettledRead<T> {
+    readonly success: boolean
+    readonly data?: T
+    readonly kind?: string
+}
+
+/** What an SWR read of one operation hands its caller: the operation's outcome, the fetch error and whether it is on its way. */
+interface SwrRead<T> {
+    readonly data: SettledRead<T> | undefined
+    readonly error?: unknown
+    readonly isLoading: boolean
+}
+
+/** Folds one SWR read into its slot: a refusal of kind `forbidden` is its own status, every other failure is an error. */
+export const slotOfSwr = <T>(read: SwrRead<T>): DataSlot<T> => {
+    if (read.isLoading) return { items: undefined, isLoading: true }
+    if (read.data === undefined) return { items: undefined, isError: read.error !== undefined }
+    if (read.data.success) return { items: read.data.data }
+    return read.data.kind === "forbidden" ? { items: undefined, isForbidden: true } : { items: undefined, isError: true }
+}
+
+/** Carries a slot's status over to the view made of its items. */
+export const mapSlot = <T, U>(slot: DataSlot<T>, map: (items: T) => U): DataSlot<U> => ({
+    ...slot,
+    items: slot.items === undefined ? undefined : map(slot.items),
+})
+
+/** The slot of a read still on its way: what a skeleton story and a region waiting on its owner render. */
+export const loadingSlot = <T>(): DataSlot<T> => ({ items: undefined, isLoading: true })

package/templates/fe/units/slot/useSlotLabels.ts.tpl

@@ -0,0 +1,8 @@
+import { useTranslations } from "next-intl"
+import type { SlotLabels } from "@/modules/types"
+
+/** Resolves the shared status copy once; the returned function adds one region's own empty sentence. */
+export const useSlotLabels = () => {
+    const t = useTranslations("status")
+    return (empty: string): SlotLabels => ({ empty, forbidden: t("forbidden"), error: t("error"), retry: t("retry") })
+}