@starci/hfs 4.16.5 → 4.17.2

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

@@ -2,11 +2,12 @@ import { useState } from "react"
 import type { ReactNode } from "react"
 import { Button } from "@starci/grammar/common"
 
-/** The resolved labels of the toggle and the content it shows; the branch owns only whether it is open. */
+/** The resolved labels of the toggle and the slot it shows; the branch owns only whether it is open, and takes no children. */
 type {{Name}}Props = {
     readonly showLabel: string
     readonly hideLabel: string
-    readonly children: ReactNode
+    /** What the toggle shows when open. */
+    readonly body: ReactNode
 }
 
 /** Holds its intrinsic state alone (open or closed); it reads no data, resolves no copy and renders below a client block. */
@@ -17,7 +18,7 @@ export const {{Name}} = (props: {{Name}}Props) => {
             <Button intent="neutral" onPress={() => setIsOpen((current) => !current)}>
                 {isOpen ? props.hideLabel : props.showLabel}
             </Button>
-            {isOpen ? props.children : null}
+            {isOpen ? props.body : null}
         </>
     )
 }

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

@@ -4,15 +4,15 @@ import { Text } from "@starci/grammar/common"
 type {{Name}}Props = {
     readonly term: string
     readonly value: string
-    readonly isSkeleton: boolean
+    readonly isLoading: boolean
 }
 
 /** A closed arrangement of Grammar parts: a term and its value, each resting as itself while its block waits. */
 export const {{Name}} = (props: {{Name}}Props) => (
     <>
-        <Text tone="muted" isSkeleton={props.isSkeleton}>
+        <Text tone="muted" isLoading={props.isLoading}>
             {props.term}
         </Text>
-        <Text isSkeleton={props.isSkeleton}>{props.value}</Text>
+        <Text isLoading={props.isLoading}>{props.value}</Text>
     </>
 )

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react"
+import { Stack } from "@starci/grammar/common"
+
+/** What {{Name}} holds: it owns a region and lays out whatever its caller puts in it. */
+type {{Name}}Props = {
+    readonly children: ReactNode
+}
+
+/** A frame owns a region of the screen and adds no content of its own; only a frame takes `children`. */
+export const {{Name}} = (props: {{Name}}Props) => <Stack gap="section">{props.children}</Stack>

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

@@ -1,11 +1,11 @@
 import type { ReactNode } from "react"
-import { PrimaryRailLayout } from "@starci/grammar/common"
+import { Grid } from "@starci/grammar/common"
 {{blockImports}}
 /** Framework-layout boundary input: the routed page of the {{segment}} segment and nothing else. */
 type {{Name}}Props = { readonly content: ReactNode }
 
 /**
- * The {{segment}} segment's frame: Grammar's PrimaryRailLayout places the routed page and {{railDoc}}. A frame only places
+ * The {{segment}} segment's frame: Grammar's Grid (kind main-rail) places the routed page and {{railDoc}}. A frame only places
  * regions and never insets a page; the Page inside owns its inset and rhythm.
  */
 export const {{Name}} = (props: {{Name}}Props) => {{frame}}

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

@@ -3,8 +3,8 @@ 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
+    readonly isLoading: 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>
+/** A fixed semantic unit over one Grammar leaf; it rests as itself by passing `isLoading` on. */
+export const {{Name}} = (props: {{Name}}Props) => <Badge isLoading={props.isLoading}>{props.label}</Badge>

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

@@ -8,7 +8,7 @@ export interface {{Name}}BaseProps {
         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
+        readonly isLoading: boolean
     }
 }
 
@@ -28,7 +28,7 @@ export const {{Name}}Base = (props: {{Name}}BaseProps) => (
                 ],
             },
 {{tabsHeader}}        }}
-        isSkeleton={props.props.isSkeleton}
+        isLoading={props.props.isLoading}
     >
 {{body}}
     </Page>

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

@@ -11,14 +11,14 @@ export const {{nameCamel}}Metadata = async (): Promise<Metadata> => {
 }
 
 /** 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 copyOf = async (isLoading: 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,
+{{emptyResolved}}{{tabsResolved}}        isLoading,
     }
 }
 

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

@@ -8,7 +8,7 @@ const READY: {{Name}}BaseProps["props"] = {
     breadcrumbLabel: "Breadcrumb",
     homeLabel: "Home",
     homeHref: "/",
-{{emptyFixture}}{{tabsFixture}}    isSkeleton: false,
+{{emptyFixture}}{{tabsFixture}}    isLoading: false,
 }
 
 /** The pure half of {{Name}}: the resolved page and its loading view, paired for the DNA gate. */
@@ -29,6 +29,6 @@ export const Ready: Story = {
 
 /** The route's loading view: the same page, its header resting in its own boxes. */
 export const ReadySkeleton: Story = {
-    args: { props: { ...READY, isSkeleton: true } },
+    args: { props: { ...READY, isLoading: true } },
     parameters: { dna: { pair: "Ready", phase: "loading" } },
 }

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

@@ -4,25 +4,26 @@ import { EmptyNotice } from "@starci/grammar/common"
 /** 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`. */
+    /** A value of the same shape as the items: while loading, the ready tree draws it with `isLoading` on each Grammar component. */
     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
+    readonly render: (items: T, isLoading: 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 { slot } = props
+    if (slot.isLoading === true) return props.render(props.placeholder, true)
+    if (slot.isForbidden === true) return props.forbidden === "hide" ? null : <EmptyNotice message={props.labels.forbidden} />
+    if (slot.isError === true) {
+        return <EmptyNotice isError 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)
+    if (slot.isEmpty === true) return <EmptyNotice message={props.labels.empty} />
+    // A refresh (`isValidating`) beside data keeps the content: it never draws a skeleton.
+    if (Array.isArray(slot.items) && slot.items.length === 0) return <EmptyNotice message={props.labels.empty} />
+    return props.render(slot.items, false)
 }

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

@@ -1,13 +1,25 @@
+/** The flags no member of `DataSlot` sets: reading one is allowed and gives `undefined`. */
+interface Unset {
+    readonly isLoading?: undefined
+    readonly isError?: undefined
+    readonly isForbidden?: undefined
+    readonly isEmpty?: undefined
+    readonly isValidating?: undefined
+}
+
 /**
- * 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.
+ * The status of one read (FE-ERROR-1), a union over the flags so an impossible mix (loading and error together) cannot be built.
+ * Only `slotOfSwr`, `slotOfReads`, `mapSlot` and `loadingSlot` build one. `items` exists only on the ready member. `isLoading` is a
+ * first load with no data. `isValidating` is a refresh beside data: the content stays and no skeleton is drawn. `isEmpty` is a
+ * finished read with nothing, never a failed one. 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.
  */
-export interface DataSlot<T> {
-    readonly items: T | undefined
-    readonly isLoading?: boolean
-    readonly isError?: boolean
-    readonly isForbidden?: boolean
-}
+export type DataSlot<T> =
+    | (Omit<Unset, "isLoading"> & { readonly isLoading: true })
+    | (Omit<Unset, "isForbidden"> & { readonly isForbidden: true })
+    | (Omit<Unset, "isError"> & { readonly isError: true })
+    | (Omit<Unset, "isEmpty" | "isValidating"> & { readonly isEmpty: true; readonly isValidating?: boolean })
+    | (Omit<Unset, "isValidating"> & { readonly items: T; readonly isValidating?: 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 {

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

@@ -11,25 +11,66 @@ interface SettledRead<T> {
 }
 
 /** 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> {
+export interface SwrRead<T> {
     readonly data: SettledRead<T> | undefined
     readonly error?: unknown
+    /** SWR's first load with no data. */
     readonly isLoading: boolean
+    /** SWR's refresh beside data. It rides on the slot and never draws a skeleton. */
+    readonly isValidating?: boolean
 }
 
-/** Folds one SWR read into its slot: a refusal of kind `forbidden` is its own status, every other failure is an error. */
+/**
+ * Folds one SWR read into its slot: a first load with no data is `isLoading` (a refresh keeps the data), a refusal of kind `forbidden`
+ * is its own status, every other failure is an error. A refresh beside data is `isValidating`.
+ */
 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 }
+    if (read.isLoading) return { isLoading: true }
+    if (read.data === undefined) return read.error !== undefined ? { isError: true } : { isEmpty: true }
+    if (read.data.success && read.data.data !== undefined) return read.isValidating === true ? { items: read.data.data, isValidating: true } : { items: read.data.data }
+    if (read.data.success) return { isEmpty: true }
+    return read.data.kind === "forbidden" ? { isForbidden: true } : { 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),
-})
+export const mapSlot = <T, U>(slot: DataSlot<T>, map: (items: T) => U): DataSlot<U> =>
+    "items" in slot ? { ...slot, items: map(slot.items) } : slot
 
 /** 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 })
+export const loadingSlot = <T>(): DataSlot<T> => ({ isLoading: true })
+
+/** The part of an SWR read a frame folds with its other reads. */
+export interface FrameRead<T> {
+    readonly data: T | undefined
+    readonly isLoading: boolean
+    readonly error?: unknown
+    readonly isValidating?: boolean
+}
+
+const slotOfFrameRead = <T>(read: FrameRead<T>): DataSlot<T> => {
+    if (read.data !== undefined) return read.isValidating === true ? { items: read.data, isValidating: true } : { items: read.data }
+    if (read.error !== undefined) return { isError: true }
+    return read.isLoading ? { isLoading: true } : { isEmpty: true }
+}
+
+/**
+ * Folds EVERY read a frame draws into one slot in a single pass. A frame never borrows the status of one of its reads for the others
+ * (lint `no-foreign-slot-status`), and never folds a read to `[]` (`no-swr-default-array`). `view` gets the reads and builds the items.
+ *
+ * - `isError` when a read failed with no data of its own: a failure never reads as empty;
+ * - `isLoading` when any read is loading with no data, unless the frame `hasDrawn` (latched after the first draw): a read that
+ *   reloads on a key change leaves the frame standing, and the region keyed by that read shows its own loading;
+ * - `isEmpty` when every read finished with nothing; otherwise the items, `view(reads)`.
+ */
+export const slotOfReads = <Reads extends Readonly<Record<string, FrameRead<unknown>>>, V>(
+    reads: Reads,
+    view: (reads: Reads) => V,
+    hasDrawn = false,
+): DataSlot<V> => {
+    const slots = Object.values(reads).map((read) => slotOfFrameRead(read))
+    if (slots.some((slot) => slot.isError === true)) return { isError: true }
+    if (slots.some((slot) => slot.isLoading === true) && !hasDrawn) return { isLoading: true }
+    if (slots.every((slot) => slot.isEmpty === true)) return { isEmpty: true }
+    const items = view(reads)
+    return Object.values(reads).some((read) => read.isValidating === true) ? { items, isValidating: true } : { items }
+}

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

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from "react"
+import type { DataSlot } from "@/modules/types"
+import { slotOfReads, type FrameRead } from "./slot.shared"
+
+/**
+ * `slotOfReads` for a component: it remembers that the frame has drawn its content, so a read that reloads on a key change (the open
+ * room, the page) leaves the frame standing. Only a first load with no data is `isLoading`.
+ */
+export const useSlotOfReads = <Reads extends Readonly<Record<string, FrameRead<unknown>>>, V>(
+    reads: Reads,
+    view: (reads: Reads) => V,
+): DataSlot<V> => {
+    const hasDrawn = useRef(false)
+    const slot = slotOfReads(reads, view, hasDrawn.current)
+    useEffect(() => {
+        if ("items" in slot) hasDrawn.current = true
+    }, [slot])
+    return slot
+}