@bettercms-ai/kit 0.1.0 → 1.0.0

package/controls/link.d.ts

@@ -0,0 +1,260 @@
+/**
+ * LINK — the ONE link element of the product (V2 HEAD kit/controls/link.tsx, DESIGN §8.7, CPO D43 · D48 · D57).
+ *
+ *  - <LinkForm>        Type (Page · CMS item · URL · Email · Phone · Section · File) → the target for that type (search over
+ *                      the host's pages and CMS items, paste detection, URL / email / phone / #anchor validation; File =
+ *                      the host's media library) → Section on the picked page → options (new tab · rel · email subject).
+ *  - <LinkPopoverBody> the link panel: what it links to now + LinkForm + Remove link · Cancel · Apply.
+ *  - <LinkField>       a link at rest (one bordered row): click edits in place (quick edit), the sliders icon opens the panel.
+ *  - <LinkPicker>      the target input inside all of the above.
+ *  - <LinkLine>        how a link READS at rest: page icon + title + path · external icon + domain · mail / phone.
+ *
+ * Where the targets come from. The kit never fetches: the host hands its own link-target query in as a React hook,
+ * `KitServices.useLinkTargets` (KitLinkServices below), and the media library as `KitServices.MediaPicker`. With no hook a
+ * page link is typed as a path and the list says so in words; with no media picker the File type is not offered.
+ * Section anchors come from the host that knows the page (SectionAnchorsProvider); without one a section is typed (#faq).
+ *
+ * Stored shape (prod `link`, adapters/values.ts linkToProd / linkFromProd). The kit value is what the field already
+ * stores: a STRING href stays a string (legacy fields and the sites that read `href={link}`), an object stays an object.
+ * An empty field takes `field.valueShape` and, with none, the string (prod LinkField's default). In the string shape the
+ * options (new tab, rel) need the object, so they hide — V2's `valueShape="string"`. An object never carries `target`
+ * (derived from newTab), `rel: "follow"` (follow = no rel) or `newTab: false`, so it reads back exactly as written.
+ *
+ * Deviations from V2, each because prod has no source for it: no "From this entry" {{token}} targets (no binding store
+ * behind them), no seeded page anchors, no fabricated CDN address for a file (a file without a public url is refused).
+ */
+import * as React from "react";
+import { type KitMediaAsset, type KitServices } from "../context";
+import type { ControlProps } from "../types";
+export type LinkType = "page" | "url" | "section" | "email" | "phone" | "file" | "entry";
+export type LinkRel = "follow" | "nofollow" | "ugc" | "sponsored";
+export type ButtonStyle = "primary" | "secondary" | "outline" | "link";
+export interface LinkValue {
+    type?: LinkType;
+    href: string;
+    /** button label / link text */
+    label?: string;
+    /** resolved title of the target (page or entry name) */
+    title?: string;
+    pageId?: string;
+    entryId?: string;
+    anchor?: string;
+    assetId?: string;
+    email?: string;
+    subject?: string;
+    phone?: string;
+    /** legacy target: read as newTab, never written */
+    target?: "_self" | "_blank";
+    newTab?: boolean;
+    rel?: LinkRel;
+    style?: ButtonStyle;
+    variant?: string;
+    size?: "sm" | "md" | "lg";
+    arrow?: boolean;
+    icon?: string;
+    fullWidth?: boolean;
+}
+/** A place a link can point at, as the host lists it. */
+export interface LinkTarget {
+    id: string;
+    title: string;
+    /** the public path ("/about", "/blog/hello") or a file's url */
+    href: string;
+    kind: "page" | "entry" | "file" | "section";
+    /** collection name for an entry, file kind for a file */
+    meta?: string;
+    /** list group: "Pages", the collection's name, "Files", "On this page" */
+    group: string;
+    /** draft · published · scheduled · archived … (shown when it is not live) */
+    status?: string;
+    /** "#faq" anchors on that page, when the host knows them */
+    anchors?: string[];
+    /** a section without an anchor yet gets it when picked */
+    onChoose?: () => void;
+}
+/**
+ * The link services a host provides next to KitServices (registerKitServices / KitServicesProvider take them as is).
+ * `useLinkTargets` is a React HOOK (called on every render of a link control), so a host passes the same function for
+ * the life of the form.
+ */
+export type KitLinkServices = Pick<KitServices, "useLinkTargets">;
+type LinkHost = {
+    targets: LinkTarget[];
+    loading: boolean;
+    error?: string;
+    unavailable: boolean;
+};
+/** The host's pages, CMS items (and files, when it lists them). */
+export declare function useLinkTargets(): LinkHost;
+/** A section on the page being edited that a link can jump to (`id` on the block). */
+export interface SectionAnchor {
+    /** "#faq" */
+    anchor: string;
+    /** what a person reads: the block's name */
+    label: string;
+    /** the block has no anchor yet: give it this one when a link picks it */
+    ensure?: () => void;
+}
+/** The host that knows the page being edited lists its section anchors, so the Section type is a pick. */
+export declare function SectionAnchorsProvider({ anchors, children }: {
+    anchors: SectionAnchor[];
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** A file from the media library as a link target, or the reason it can't be one. */
+export declare function fileTarget(a: Pick<KitMediaAsset, "id" | "name" | "url">): LinkTarget | {
+    problem: string;
+};
+export declare const normLink: (v: unknown) => LinkValue;
+export declare function detectType(raw: string): LinkType;
+export declare const LINK_TYPES: {
+    type: LinkType;
+    label: string;
+    icon: React.ReactNode;
+    placeholder: string;
+    target: string;
+}[];
+/** The target a value points at: by id first, then by an exact path ("/about" typed by hand still reads as About). */
+export declare function findTarget(targets: LinkTarget[], v: LinkValue): LinkTarget | undefined;
+/** The final href for a link value. */
+export declare function hrefOf(v: LinkValue): string;
+/** Why a link can't be saved yet, in plain words. Undefined when it is fine (or empty). */
+export declare function linkProblem(v: LinkValue): string | undefined;
+/** One list for every link editor (dropdown, never a segmented row — D40). */
+export declare const REL_ITEMS: {
+    value: LinkRel;
+    label: string;
+    description: string;
+}[];
+export declare const hasLink: (v: LinkValue) => boolean;
+export declare const TARGET_KEYS: {
+    readonly title: undefined;
+    readonly pageId: undefined;
+    readonly entryId: undefined;
+    readonly assetId: undefined;
+    readonly anchor: undefined;
+};
+/** The value a picked target produces (keeps label, style and options). */
+export declare function withTarget(v: LinkValue, t: LinkTarget): LinkValue;
+/** The value typed text produces (auto-detects URL / email / phone / #section unless the type was chosen). */
+export declare function withText(v: LinkValue, s: string, type?: LinkType): LinkValue;
+/** Clean a value before it is stored: add https:// to bare domains, refuse script URLs, store the href the site renders. */
+export declare function finalizeLink(v: LinkValue): LinkValue | null;
+/**
+ * The object as prod stores it, keyed like the value it replaces (`original`), so an edit changes only what was edited:
+ * no undefined keys; no `rel: "follow"` (follow is no rel: the backend normalises it away and a button refuses it); no
+ * `newTab: false` and no `target` unless the stored value had that key (a stored `target` is kept in sync with newTab,
+ * and is then the one that carries it).
+ */
+export declare function storedLink<T extends LinkValue>(v: T, original?: unknown): T;
+export declare function linkIcon(v: LinkValue, target?: LinkTarget): React.ReactNode;
+/** Primary + secondary text: page title + path · domain + rest of the URL · address · number. */
+export declare function describeLink(v: LinkValue, target?: LinkTarget): {
+    primary: string;
+    secondary?: string;
+};
+/** What a person reads for a link (one string — menus, aria labels, history). */
+export declare const linkText: (v: LinkValue) => string;
+/** A link at rest: icon · title (fg) · path (fg-3) · new-tab mark. Empty → "Add link". */
+export declare function LinkLine({ v, target, placeholder, className }: {
+    v: LinkValue;
+    target?: LinkTarget;
+    placeholder?: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface LinkPickerProps {
+    value: LinkValue;
+    /** every change: typed text, a picked target, a cleared value */
+    onChange: (v: LinkValue) => void;
+    /** a target was chosen from the list (quick editors commit here) */
+    onPick?: (v: LinkValue) => void;
+    /** Enter with no list row active */
+    onEnter?: (v: LinkValue) => void;
+    /** Escape with the list closed */
+    onEscape?: () => void;
+    autoFocus?: boolean;
+    /** open straight into search (quick edit), even when a target is picked */
+    startSearching?: boolean;
+    id?: string;
+    "aria-label"?: string;
+    size?: "sm" | "md";
+    /** no border of its own — it sits inside a unit that already draws one (button field) */
+    bare?: boolean;
+    /** the host shows its own type control (link panel): hide the inline type menu and search only this type */
+    lockedType?: LinkType;
+    /** results render in the flow under the input instead of a floating list — panels/popovers, never over them */
+    inlineList?: boolean;
+    /** the link types this place allows. Default: all of them */
+    types?: LinkType[];
+    /** the value can't be saved as it is (shown as the field's error state) */
+    invalid?: boolean;
+    "aria-describedby"?: string;
+    className?: string;
+}
+export declare function LinkPicker({ value, onChange, onPick, onEnter, onEscape, autoFocus, startSearching, id, "aria-label": ariaLabel, size, bare, lockedType, inlineList, types, invalid, "aria-describedby": describedBy, className, }: LinkPickerProps): import("react/jsx-runtime").JSX.Element;
+export declare function LinkOptions({ v, onChange, compact, disabled }: {
+    v: LinkValue;
+    onChange: (v: LinkValue) => void;
+    compact?: boolean;
+    disabled?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkForm({ value, onChange, onEnter, hideOptions, types, autoFocus, readOnly, className, }: {
+    value: LinkValue;
+    onChange: (v: LinkValue) => void;
+    /** Enter in the target with a value that can be saved */
+    onEnter?: (v: LinkValue) => void;
+    /** string-only values: no new tab / rel */
+    hideOptions?: boolean;
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+    /** focus the Type control on open (D48: never the search) */
+    autoFocus?: boolean;
+    /** the lens can't edit the link: every control is disabled */
+    readOnly?: boolean;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkPopoverBody({ initial, onSave, onDetach, onCancel, hideOptions, types, }: {
+    initial: LinkValue;
+    onSave: (v: LinkValue) => void;
+    onDetach?: () => void;
+    onCancel?: () => void;
+    /** string-only fields: no new tab / rel */
+    hideOptions?: boolean;
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkQuickEdit({ value, onCommit, onDone, ariaLabel, size, bare, types, }: {
+    value: LinkValue;
+    /** null = cleared */
+    onCommit: (v: LinkValue | null) => void;
+    onDone: () => void;
+    ariaLabel: string;
+    size?: "sm" | "md";
+    bare?: boolean;
+    types?: LinkType[];
+}): import("react/jsx-runtime").JSX.Element;
+export interface LinkFieldProps {
+    /** a LinkValue or a plain href string */
+    value: unknown;
+    /** null = cleared (object shape); "" = cleared (string shape) */
+    onChange: (v: LinkValue | string | null) => void;
+    /** "string": the value is the href alone. New tab and rel need the object shape, so they hide. */
+    valueShape?: "string" | "object";
+    id?: string;
+    "aria-label": string;
+    readOnly?: boolean;
+    size?: "sm" | "md";
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+    invalid?: boolean;
+    placeholder?: string;
+    className?: string;
+}
+export declare function LinkField({ value, onChange: write, valueShape, id: idProp, "aria-label": label, readOnly, size, types, invalid, placeholder, className }: LinkFieldProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The shape a link field writes: the shape its value already has (a string stays a string, an object an object), and
+ * for an empty field `field.valueShape`, else the string prod stores by default.
+ */
+export declare function linkShapeOf(value: unknown, valueShape?: "string" | "object"): "string" | "object";
+/** The Block Kit `link` field: the LinkField above, sized for the form it sits in. */
+export declare function LinkControl({ value, onChange, readOnly, id, field, invalid }: ControlProps): import("react/jsx-runtime").JSX.Element;
+export {};