dsh-featherhunter-plugin-base 0.0.0-stage → 0.0.2-drill

package/dist/client/modal.d.ts

@@ -0,0 +1,42 @@
+import type { Group, Lang } from "../core/types";
+import { type TextOverrides } from "./texts";
+/** Everything the modal needs; built by createBaseUI's openContactModal. */
+export interface ContactModalConfig {
+    doc: Document;
+    lang: Lang;
+    groups: readonly Group[];
+    /** Already clamped to 1..4 columns (and to the group count). */
+    columns: number;
+    trigger: HTMLElement | null;
+    fallbackUrl: string;
+    texts?: TextOverrides;
+    /** Returns null when no image is available (card degrades to a link). */
+    resolveQr: (group: Group) => string | null;
+    /** Clock override for date-dependent validity text. */
+    now?: Date;
+}
+export interface ContactModalUpdate {
+    groups?: readonly Group[];
+    /** Already clamped to 1..4 columns. */
+    columns?: number;
+    /** Returns null when no image is available (card degrades to a link). */
+    resolveQr?: (group: Group) => string | null;
+    fallbackUrl?: string;
+    now?: Date;
+}
+export interface ContactModalHandle {
+    dialog: HTMLDialogElement;
+    /** Destroy the dialog; restore focus by default. */
+    close: (restoreFocus?: boolean) => void;
+    /**
+     * Re-render the group cards in place. Used when the remote manifest arrives
+     * after the baseline was painted, so the dialog is never rebuilt.
+     */
+    update: (next: ContactModalUpdate) => void;
+}
+/**
+ * Build the contact dialog, enter it into the top layer with showModal() and
+ * wire the close paths (Esc, backdrop, close button). The dialog element is
+ * the public seam: tests and hosts can query it in the document.
+ */
+export declare function mountContactModal(config: ContactModalConfig): ContactModalHandle;

package/dist/client/plugins.d.ts

@@ -0,0 +1,44 @@
+import type * as ReactNamespace from "react";
+import type { Lang, PluginEntry } from "../core/types";
+/**
+ * Default row cap of the author plugin card. The list is the five finalised
+ * plugins (contact/plugins.json); after dropping the host plugin four remain,
+ * so five is a natural ceiling that never hides a sibling by accident.
+ */
+export declare const DEFAULT_MAX_ROWS = 5;
+/** Options that decide which plugin rows are visible. */
+export interface AuthorPluginRowsOptions {
+    /** Full plugin list, usually `manifest.plugins`. */
+    plugins: readonly PluginEntry[];
+    /** Id of the host plugin; excluded unless `showSelf` is on. */
+    selfId?: string;
+    /** Show the host plugin itself. */
+    showSelf?: boolean;
+    /** Hard cap on rendered rows (default {@link DEFAULT_MAX_ROWS}). */
+    maxRows?: number;
+}
+/**
+ * Visible rows: data order (order asc), host plugin dropped unless asked for,
+ * then capped. An undecorated list keeps the exact order of the manifest.
+ */
+export declare function selectAuthorPlugins(options: AuthorPluginRowsOptions): PluginEntry[];
+/**
+ * Link target of one row: the explicit `url` when the data provides one,
+ * otherwise the canonical GitHub repository page.
+ */
+export declare function pluginHref(plugin: PluginEntry): string;
+/** Everything the pure renderer needs; built by createBaseUI's wire-up. */
+export interface RenderAuthorPluginsOptions extends AuthorPluginRowsOptions {
+    /** Injected runtime: the package never imports React itself. */
+    React: typeof ReactNamespace;
+    lang: Lang;
+    /** Already localised, already overridden card title. */
+    title: string;
+    className?: string;
+}
+/**
+ * Render the settings-panel card, or null when nothing is left to show: an
+ * empty list, a failed manifest, or a list containing only the host plugin
+ * must not leave an empty container in the settings page.
+ */
+export declare function renderAuthorPlugins(options: RenderAuthorPluginsOptions): ReactNamespace.ReactElement | null;

package/dist/client/styles.d.ts

@@ -0,0 +1,13 @@
+/** Style element id shared by every widget of this package. */
+export declare const BASE_STYLE_ID = "dsh-base-style";
+/**
+ * One stylesheet for the whole package, injected once per document.
+ *
+ * The modal mirrors a README-in-a-dialog: 800px panel, centered heading,
+ * centered card grid (four columns at most) and 10-13px type. Narrow screens
+ * collapse the grid through media queries because the inline column count only
+ * expresses the data-driven part of the layout.
+ */
+export declare const BASE_CSS: string;
+/** Inject the stylesheet once per document. */
+export declare function ensureBaseStyles(doc: Document): void;

package/dist/client/texts.d.ts

@@ -0,0 +1,11 @@
+import type { Lang } from "../core/types";
+/** Message ids shared by the widgets and the contact modal. */
+export type TextKey = "contact" | "contactHint" | "kicker" | "modalTitle" | "welcome" | "scanHint" | "mobileHint" | "close" | "copyHint" | "copied" | "expired" | "fallback" | "plugins";
+export type TextOverrides = Partial<Record<string, string>>;
+/**
+ * Built-in copy. The wording mirrors the README contact block so the settings
+ * panel and the README read the same; callers can override any message id.
+ */
+export declare const MESSAGES: Record<Lang, Record<TextKey, string>>;
+/** Resolve one message id: caller overrides win, then the detected language. */
+export declare function resolveText(key: TextKey, lang: Lang, overrides?: TextOverrides): string;

package/dist/client/types.d.ts

@@ -0,0 +1,90 @@
+import type { ComponentType } from "react";
+import type { Group, Lang, PluginEntry } from "../core/types";
+import type { ContentLoader, FetchLike } from "./content";
+import type { TextOverrides } from "./texts";
+/**
+ * Resolve the image source for a group's QR code.
+ *
+ * A null / undefined result means "no image available": the card degrades to
+ * the fallback link instead of rendering a broken or expired QR code. Ticket
+ * 05 injects a CDN resolver here; the default only reads bundled baseline
+ * codes.
+ */
+export type QrResolver = (group: Group) => string | null | undefined;
+/** Options for createBaseUI. */
+export interface BaseUIOptions {
+    /** Force a language instead of auto-detecting it. */
+    lang?: Lang | string;
+    /** Id of the host plugin; excluded from the author plugin list. */
+    selfId?: string;
+    /** Manifest URL override (defaults to the published CDN manifest). */
+    manifestUrl?: string;
+    /** Fetch implementation override (testing seam). */
+    fetchImpl?: FetchLike;
+    /** Pre-built content loader override (testing seam). */
+    contentLoader?: ContentLoader;
+    /** Text overrides keyed by message id. */
+    texts?: TextOverrides;
+    /** Max columns of the contact grid (hard ceiling: 4). */
+    columns?: number;
+    /** URL used when a group QR code expired or is unavailable. */
+    fallbackUrl?: string;
+    /** QR image resolver; defaults to the bundled baseline data URIs. */
+    resolveQr?: QrResolver;
+    /** Show the host plugin itself in the author plugin list. */
+    showSelf?: boolean;
+    /** Max rows of the author plugin list (default 5). */
+    maxRows?: number;
+}
+export interface ContactButtonProps {
+    className?: string;
+    /** Overrides the default tooltip / aria label. */
+    title?: string;
+    /** Render only the icon. */
+    iconOnly?: boolean;
+    /** Icon size in px (14 / 16 / 18, default 16). */
+    size?: 14 | 16 | 18;
+}
+export interface ContactRowProps {
+    className?: string;
+    label?: string;
+    /** Small hint next to the button. */
+    hint?: string;
+}
+export interface AuthorPluginsProps {
+    className?: string;
+    title?: string;
+    lang?: Lang;
+    /** Id of the host plugin; defaults to the createBaseUI option. */
+    selfId?: string;
+    /** Show the host plugin itself instead of dropping it. */
+    showSelf?: boolean;
+    plugins?: PluginEntry[];
+    /** Hard cap on rendered rows (default 5). */
+    maxRows?: number;
+}
+export interface OpenContactModalOptions {
+    /** Element that opened the modal; focus returns here on close. */
+    trigger?: HTMLElement | null;
+    /** Groups override (defaults to the baseline manifest). Empty falls back. */
+    groups?: Group[];
+    lang?: Lang | string;
+    texts?: TextOverrides;
+    /** Max columns of the contact grid (hard ceiling: 4). */
+    columns?: number;
+    /** URL used when a group QR code expired or is unavailable. */
+    fallbackUrl?: string;
+    /** QR image resolver; defaults to the bundled baseline data URIs. */
+    resolveQr?: QrResolver;
+    /** Clock override for date-dependent validity text (testing seam). */
+    now?: Date;
+}
+/** Widget set returned by createBaseUI. */
+export interface BaseUI {
+    ContactButton: ComponentType<ContactButtonProps>;
+    ContactRow: ComponentType<ContactRowProps>;
+    AuthorPlugins: ComponentType<AuthorPluginsProps>;
+    openContactModal: (options?: OpenContactModalOptions) => () => void;
+    closeContactModal: () => void;
+    preloadContent: () => Promise<void>;
+}

package/dist/core/baseline.d.ts

@@ -0,0 +1,2 @@
+import type { BaselineContent } from "./types";
+export declare const BASELINE: BaselineContent;

package/dist/core/index.d.ts

@@ -0,0 +1,40 @@
+import type { I18nText, Lang, Manifest } from "./types";
+export * from "./types";
+export { BASELINE } from "./baseline";
+/** Pick the localized variant, falling back to the other language. */
+export declare function pickText(text: I18nText | undefined, lang: Lang): string;
+export interface LangHints {
+    /** Explicit user setting. */
+    explicit?: string | null;
+    /** `<html lang>` of the host page. */
+    htmlLang?: string | null;
+    /** `navigator.languages` of the host page. */
+    navigatorLanguages?: readonly string[] | null;
+}
+/**
+ * Language fallback chain: explicit setting -> page `<html lang>` ->
+ * `navigator.languages` -> `zh`.
+ */
+export declare function resolveLang(hints?: LangHints): Lang;
+/** Copy sorted by display order (stable, input untouched). */
+export declare function sortByOrder<T extends {
+    order: number;
+}>(items: readonly T[]): T[];
+/** Strict `YYYY-MM-DD` parser (UTC midnight). Invalid dates return null. */
+export declare function parseDateOnly(value: string): Date | null;
+/** `validUntil` is inclusive; a group without `validUntil` never expires. */
+export declare function isExpired(validUntil: string | undefined, now?: Date): boolean;
+export interface ValidityOptions {
+    lang: Lang;
+    now?: Date;
+}
+/**
+ * Human validity line for the modal footnote. Returns null for permanent codes
+ * and for expired ones (the caller falls back to the link).
+ */
+export declare function formatValidity(validUntil: string | undefined, options: ValidityOptions): string | null;
+/**
+ * Validate a published `data/manifest.json` payload. Throws on the first
+ * structural problem so a bad deploy fails loudly instead of rendering blanks.
+ */
+export declare function parseManifest(raw: unknown): Manifest;