forgebook 0.3.3 → 0.4.1

package/dist/src/shell/pageTagView.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LazyView, lazyModule } from "./lazyModule.js";
+/** What the tags draw on the page, loaded on first use. */
+const PAGE_TAG_VIEW = lazyModule(() => import("./TagViews.js").then((module) => module.TagView));
+/**
+ * What the tags draw in one place of a component's page, once its code is there.
+ *
+ * @param props - the place, and what it reads.
+ */
+export const PageTagView = (props) => (_jsx(LazyView, { module: PAGE_TAG_VIEW, props: props, loading: null, failed: () => null }));

package/dist/src/shell/playMemory.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Keeps a reader's play switch for their next visits, on what a browser keeps for a catalogue. Loaded with the parts that
+ * show the switch; the shell reads the choice back with its settings (`catalogueContext.ts`).
+ *
+ * @module
+ */
+import type { CatalogueSettings, PlaySwitch } from "../catalogue.ts";
+/**
+ * Keeps a reader's choice.
+ *
+ * @param catalogue - the catalogue, whose id the choice is kept under.
+ * @param play - the choice.
+ */
+export declare const rememberPlay: (catalogue: Pick<CatalogueSettings, "id">, play: PlaySwitch) => void;

package/dist/src/shell/playMemory.js

@@ -0,0 +1,8 @@
+import { writeStored } from "./useStored.js";
+/**
+ * Keeps a reader's choice.
+ *
+ * @param catalogue - the catalogue, whose id the choice is kept under.
+ * @param play - the choice.
+ */
+export const rememberPlay = (catalogue, play) => writeStored(`${catalogue.id}:play`, play);

package/dist/src/shell/propNotes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The sentences the API reference writes under a prop, and under a component that lists none: when a variant's prop can
+ * be passed, why a type is not the one its source writes, why no props are listed. Used by `ApiReference.tsx`.
+ *
+ * @remarks
+ * The shell checks these fields loosely when the docs arrive, so a reason it does not know is left out here rather
+ * than drawn wrong.
+ *
+ * @module
+ */
+import type { ComponentDocs, PropDocs } from "../componentDocs.ts";
+/**
+ * A prop's notes, in the order they are drawn: when it can be passed, then each note on its type.
+ *
+ * @param prop - the prop's condition and notes.
+ */
+export declare const propNoteTexts: (prop: Pick<PropDocs, "onlyWhen" | "notes">) => string[];
+/**
+ * Why a component lists no props, or none when its props are read.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const propsNoteText: (docs: Pick<ComponentDocs, "propsNote">) => string | undefined;

package/dist/src/shell/propNotes.js

@@ -0,0 +1,37 @@
+import { codeSpan } from "./codeSpans.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+/**
+ * A prop's notes, in the order they are drawn: when it can be passed, then each note on its type.
+ *
+ * @param prop - the prop's condition and notes.
+ */
+export const propNoteTexts = (prop) => {
+    const { onlyWhen } = prop;
+    const condition = onlyWhen === undefined
+        ? []
+        : [
+            LATER_STRINGS.propOnlyWhen(codeSpan(onlyWhen.prop), onlyWhen.values.map((value) => codeSpan(typeof value === "string" ? JSON.stringify(value) : String(value))), onlyWhen.orOmitted === true)
+        ];
+    const types = (prop.notes ?? []).flatMap((note) => {
+        if (note.reason === "generic") {
+            return [LATER_STRINGS.propGeneric(codeSpan(note.parameter), codeSpan(note.type), note.shownAs)];
+        }
+        if (note.reason === "unresolved")
+            return [LATER_STRINGS.propUnresolved(codeSpan(note.name))];
+        return note.reason === "any" ? [LATER_STRINGS.propAny] : [];
+    });
+    return [...condition, ...types];
+};
+/**
+ * Why a component lists no props, or none when its props are read.
+ *
+ * @param docs - the component's docs.
+ */
+export const propsNoteText = (docs) => {
+    const note = docs.propsNote;
+    if (note?.reason === "untyped")
+        return LATER_STRINGS.propsUntyped;
+    if (note?.reason === "no-signature")
+        return LATER_STRINGS.propsNoSignature;
+    return note?.reason === "outside-package" ? LATER_STRINGS.propsOutsidePackage(note.count) : undefined;
+};

package/dist/src/shell/refIndexLoad.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A composed catalogue's index, fetched once per page when its section is first opened or one of its stories is shown.
+ *
+ * @remarks
+ * Read with no credentials: the index is public, and a cookie of the other host has nothing to do with it. A failure is
+ * kept too, so a section opened again says why without asking again; the page's next load tries once more.
+ *
+ * @module
+ */
+import { type CatalogueRef, type RefIndex } from "../catalogueRefs.ts";
+/**
+ * A composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ * @returns the index; rejected with the reason it could not be read.
+ */
+export declare const loadRefIndex: (ref: CatalogueRef) => Promise<RefIndex>;

package/dist/src/shell/refIndexLoad.js

@@ -0,0 +1,38 @@
+/**
+ * A composed catalogue's index, fetched once per page when its section is first opened or one of its stories is shown.
+ *
+ * @remarks
+ * Read with no credentials: the index is public, and a cookie of the other host has nothing to do with it. A failure is
+ * kept too, so a section opened again says why without asking again; the page's next load tries once more.
+ *
+ * @module
+ */
+import { refIndexAddress, refIndexOf } from "../catalogueRefs.js";
+import { REF_STRINGS } from "./refStrings.js";
+/** Each composed catalogue's index, by its address, as fetched once. */
+const loads = new Map();
+/** Fetches and reads an index. */
+const fetchIndex = async (address) => {
+    const answer = await fetch(address, { credentials: "omit" });
+    if (!answer.ok)
+        throw new Error(`${answer.status} ${answer.statusText}`.trim());
+    const index = refIndexOf(await answer.json());
+    if (index === undefined)
+        throw new Error(REF_STRINGS.notIndex);
+    return index;
+};
+/**
+ * A composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ * @returns the index; rejected with the reason it could not be read.
+ */
+export const loadRefIndex = (ref) => {
+    const address = refIndexAddress(ref);
+    const known = loads.get(address);
+    if (known !== undefined)
+        return known;
+    const load = fetchIndex(address);
+    loads.set(address, load);
+    return load;
+};

package/dist/src/shell/refParts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What the shell draws of the composed catalogues (`refs`): their sidebar sections and the page of one of their stories.
+ * The generated page imports it (`forgebook/shell/refs`) only for a catalogue that composes one, so the others' first
+ * load carries not even the way to it.
+ *
+ * @remarks
+ * One module for both places, so a catalogue that composes others loads one chunk for them, and the shell keeps one
+ * slot type: a part drawn with the place it is drawn in.
+ *
+ * @module
+ */
+import type { ComponentType, ReactNode } from "react";
+import type { CatalogueRef } from "../catalogueRefs.ts";
+import { type RefStoryPageProps } from "./RefStoryPage.tsx";
+import { type SidebarRefsProps } from "./SidebarRefs.tsx";
+/** A part of the composed catalogues, with the place it is drawn in. */
+export type RefPartProps = ({
+    readonly place: "sidebar";
+} & SidebarRefsProps) | ({
+    readonly place: "page";
+} & RefStoryPageProps);
+/** The composed catalogues, as the generated page hands them to the shell. */
+export type ShellRefs = {
+    /** The catalogues, in the configuration's order. */
+    readonly catalogues: readonly CatalogueRef[];
+    /** Loads what draws them (`RefPart`). */
+    readonly load: () => Promise<ComponentType<RefPartProps>>;
+};
+/**
+ * A part of the composed catalogues: the sidebar's sections, or a story's page.
+ *
+ * @param props - the place, and that part's props.
+ */
+export declare const RefPart: (props: RefPartProps) => ReactNode;

package/dist/src/shell/refParts.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RefStoryPage } from "./RefStoryPage.js";
+import { SidebarRefs } from "./SidebarRefs.js";
+/**
+ * A part of the composed catalogues: the sidebar's sections, or a story's page.
+ *
+ * @param props - the place, and that part's props.
+ */
+export const RefPart = (props) => props.place === "sidebar" ? _jsx(SidebarRefs, { ...props }) : _jsx(RefStoryPage, { ...props });

package/dist/src/shell/refStory.css

@@ -0,0 +1,21 @@
+@layer catalogue {
+  .forgebook-ref-story {
+    overflow: auto;
+  }
+  .forgebook-ref-story__note {
+    margin: 0.25rem 0 0;
+    font: var(--forgebook-text-caption);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-ref-story__stage {
+    padding: 1rem;
+  }
+  .forgebook-ref-story__frame {
+    display: block;
+    width: 100%;
+    border: 0;
+    border-radius: var(--forgebook-radius-card);
+    box-shadow: 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
+    background: var(--forgebook-surface);
+  }
+}

package/dist/src/shell/refStrings.d.ts

@@ -0,0 +1,13 @@
+/** The composed catalogues' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export declare const REF_STRINGS: {
+    section: (title: string) => string;
+    loading: string;
+    empty: string;
+    unreadable: (title: string, reason: string) => string;
+    notIndex: string;
+    storyTitle: (story: string, catalogue: string) => string;
+    openThere: (catalogue: string) => string;
+    readOnly: string;
+    onFramesOrigin: (title: string) => string;
+    unknownRef: (id: string) => string;
+};

package/dist/src/shell/refStrings.js

@@ -0,0 +1,21 @@
+/**
+ * The words of the composed catalogues (`refs`): their sidebar section and their story's page, loaded with them, so a
+ * catalogue that composes none carries none. A catalogue replaces them as any other text of the shell
+ * (`strings: { "refs.loading": "Caricamento…" }`).
+ *
+ * @module
+ */
+import { textsOfGroup } from "./strings.js";
+/** The composed catalogues' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export const REF_STRINGS = textsOfGroup("refs", {
+    section: (title) => `${title}, another catalogue`,
+    loading: "Loading its stories…",
+    empty: "It lists no story",
+    unreadable: (title, reason) => `${title} could not be read: ${reason}. It is built with forgebook build --agent-index, and its host lets this catalogue fetch its index (CORS).`,
+    notIndex: "its forgebook-agent.json is not an index this version reads",
+    storyTitle: (story, catalogue) => `${story}, from ${catalogue}`,
+    openThere: (catalogue) => `Open in ${catalogue}`,
+    readOnly: "Shown from another catalogue, read-only: its controls and panel are in its own page.",
+    onFramesOrigin: (title) => `${title} is served on the origin this catalogue's stories run on, where it would share their storage: serve it elsewhere.`,
+    unknownRef: (id) => `No composed catalogue "${id}" in this configuration: it may have been removed. Pick one in the sidebar.`
+});

package/dist/src/shell/search.css

@@ -38,7 +38,7 @@
     gap: 0.75rem;
     margin: 0;
     padding: 0.5rem 0.75rem;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
     box-shadow: inset 0 -1px 0 var(--forgebook-separator);
   }
@@ -59,7 +59,7 @@
     flex: none;
     margin: 0;
     padding: 0.375rem 0.75rem;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
     box-shadow: inset 0 1px 0 var(--forgebook-separator);
   }
@@ -67,7 +67,7 @@
     padding: 0 0.25rem;
     border-radius: var(--forgebook-radius-control-small);
     box-shadow: inset 0 0 0 1px var(--forgebook-edge);
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
   }
   @media (hover: none) {
     .forgebook-search-panel__keys {
@@ -100,26 +100,26 @@
     margin-inline-start: 0.75rem;
   }
   .forgebook-result__name {
-    font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-label);
   }
   .forgebook-result__place {
     flex: 1;
     min-width: 0;
     overflow: hidden;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
     text-overflow: ellipsis;
     white-space: nowrap;
   }
   .forgebook-result__kind {
     flex: none;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-result__why {
     flex: none;
     min-width: 3.5rem;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-result__own .forgebook-result__why {
@@ -135,14 +135,14 @@
     min-width: 0;
   }
   .forgebook-result__label {
-    font: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-compact);
     overflow-wrap: anywhere;
   }
   .forgebook-result__label[data-code] {
-    font: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono);
   }
   .forgebook-result__snippet {
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
     overflow-wrap: anywhere;
   }
@@ -151,7 +151,7 @@
     gap: 0.75rem;
     margin: 0;
     padding: 0 0.5rem 0.25rem calc(0.75rem + 0.5rem);
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-search-panel mark {