@takuhon/ui 0.9.0 → 0.10.0

package/dist/admin/index.d.ts

@@ -0,0 +1,416 @@
+import { ValidationError, LocaleTag, Profile, Link, Career, Project, Skill, Settings, Takuhon } from '@takuhon/core';
+
+/**
+ * Field-error plumbing shared by the admin form components.
+ *
+ * Validation failures reach the editor in two shapes that mean the same thing:
+ *
+ * - `@takuhon/core`'s {@link ValidationError}, produced by a client-side
+ *   `validate()` call, carries an RFC 6901 `pointer` such as
+ *   `"/profile/displayName/en"`.
+ * - The server's RFC 7807 response (`api.md §5`) carries the same location as a
+ *   `path` with a leading `#` fragment marker, e.g. `"#/profile/displayName/en"`.
+ *
+ * Both are normalized to a single canonical pointer so a field can look up its
+ * own errors regardless of where they came from.
+ */
+
+/** A field error in either the core (`pointer`) or RFC 7807 wire (`path`) shape. */
+interface FieldErrorLike {
+    pointer?: string;
+    path?: string;
+    message: string;
+}
+/**
+ * Canonical RFC 6901 pointer: no leading `#`, a leading `/` for any non-root
+ * location, and `""` for the document root. Idempotent.
+ */
+declare function canonicalPointer(raw: string): string;
+/** Maps a canonical pointer to the messages reported at that exact location. */
+type FieldErrorIndex = ReadonlyMap<string, readonly string[]>;
+/** Group a flat error list by canonical pointer, preserving message order. */
+declare function indexErrors(errors: readonly FieldErrorLike[]): FieldErrorIndex;
+/** Convenience over {@link indexErrors} for a core `validate()` failure list. */
+declare function indexValidationErrors(errors: readonly ValidationError[]): FieldErrorIndex;
+/** Messages reported at exactly `pointer` (empty array when none). */
+declare function errorsAt(index: FieldErrorIndex, pointer: string): readonly string[];
+/**
+ * Whether any error sits at or below `prefix` — used to badge a section or a
+ * repeater item that contains an invalid field deeper in the tree.
+ */
+declare function hasErrorsUnder(index: FieldErrorIndex, prefix: string): boolean;
+/**
+ * All messages at or below `prefix`, in pointer order. Used by aggregate
+ * controls (a comma-separated list edited as one field) so item-level failures
+ * reported at `${prefix}/${itemIndex}` still surface on the single input.
+ */
+declare function collectErrorsUnder(index: FieldErrorIndex, prefix: string): string[];
+/** An empty index, handy as a default prop. */
+declare const NO_FIELD_ERRORS: FieldErrorIndex;
+
+/** Identifiers a {@link Field} hands to the control it wraps. */
+interface FieldControlProps {
+    /** `id` for the control, paired with the rendered `<label htmlFor>`. */
+    controlId: string;
+    /** `aria-describedby` value linking the control to its hint/error text. */
+    describedBy: string | undefined;
+    /** Whether the control should advertise `aria-invalid`. */
+    invalid: boolean;
+}
+interface FieldProps {
+    /** Visible label text. */
+    label: string;
+    /** Validation messages to render beneath the control. */
+    errors?: readonly string[];
+    /** Optional helper text shown between the label and the control. */
+    hint?: string;
+    /** Marks the field visually and via `aria-required` on the control. */
+    required?: boolean;
+    /** Render the control, wired with the supplied accessibility ids. */
+    children: (props: FieldControlProps) => React.ReactNode;
+}
+/**
+ * Layout + accessibility wrapper for a single form control. Owns the `id`
+ * wiring so the label, hint, error list, and control stay associated for
+ * screen readers (WCAG 2.1 AA, spec §8.5). Presentational only — it holds no
+ * value state; the wrapped control is controlled by its parent.
+ */
+declare function Field({ label, errors, hint, required, children }: FieldProps): React.JSX.Element;
+
+interface TextFieldProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    errors?: readonly string[];
+    hint?: string;
+    required?: boolean;
+    placeholder?: string;
+    /**
+     * HTML input type. Defaults to `'text'`; `'url'` for link/avatar URLs,
+     * `'month'` for `YearMonth` values (a native month picker emits `YYYY-MM`).
+     */
+    type?: 'text' | 'url' | 'email' | 'month';
+    inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
+}
+/** A labelled single-line text input wired for accessibility via {@link Field}. */
+declare function TextField({ label, value, onChange, errors, hint, required, placeholder, type, inputMode, }: TextFieldProps): React.JSX.Element;
+
+interface TextAreaFieldProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    errors?: readonly string[];
+    hint?: string;
+    required?: boolean;
+    placeholder?: string;
+    rows?: number;
+}
+/** A labelled multi-line text input wired for accessibility via {@link Field}. */
+declare function TextAreaField({ label, value, onChange, errors, hint, required, placeholder, rows, }: TextAreaFieldProps): React.JSX.Element;
+
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface SelectFieldProps {
+    label: string;
+    value: string;
+    options: readonly SelectOption[];
+    onChange: (value: string) => void;
+    errors?: readonly string[];
+    hint?: string;
+    required?: boolean;
+}
+/** A labelled `<select>` wired for accessibility via {@link Field}. */
+declare function SelectField({ label, value, options, onChange, errors, hint, required, }: SelectFieldProps): React.JSX.Element;
+
+interface CheckboxFieldProps {
+    label: string;
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+}
+/**
+ * A labelled checkbox. Laid out checkbox-first (distinct from the stacked
+ * {@link Field} controls), with the label associated via `htmlFor`.
+ */
+declare function CheckboxField({ label, checked, onChange }: CheckboxFieldProps): React.JSX.Element;
+
+interface LocaleTabsProps {
+    /** Group label, e.g. `"Display name"`. */
+    label: string;
+    /** Current localized value (BCP-47 tag → string), or undefined when empty. */
+    value: Record<LocaleTag, string> | undefined;
+    /** Locales offered as tabs (typically `settings.availableLocales`). */
+    locales: readonly LocaleTag[];
+    /**
+     * Receives the next localized record. Empty strings are pruned, and a record
+     * that becomes empty is reported as `undefined` so the field is omitted
+     * rather than emitted as `{}` (which fails the schema's `minProperties`).
+     */
+    onChange: (next: Record<LocaleTag, string> | undefined) => void;
+    /** Render a `<textarea>` instead of an `<input>` for body-length text. */
+    multiline?: boolean;
+    required?: boolean;
+    hint?: string;
+    /** Full error index; per-locale errors are looked up at `${pointer}/${locale}`. */
+    errors?: FieldErrorIndex;
+    /** Base RFC 6901 pointer to this localized field, e.g. `/profile/displayName`. */
+    pointer?: string;
+    /** Render a friendlier tab label than the raw locale tag. */
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/**
+ * Edits a localized string map (`LocalizedTitle` / `LocalizedBody`) behind one
+ * tab per locale (spec §14.2 "多言語タブ"). Implements the WAI-ARIA Tabs
+ * pattern — roving tabindex, arrow/Home/End navigation, a single shared
+ * `tabpanel` — so it stays keyboard-operable and screen-reader-correct
+ * (WCAG 2.1 AA, spec §8.5).
+ */
+declare function LocaleTabs({ label, value, locales, onChange, multiline, required, hint, errors, pointer, formatLocale, }: LocaleTabsProps): React.JSX.Element;
+
+interface RepeaterProps<T> {
+    /** Group caption rendered as the fieldset legend, e.g. `"Links"`. */
+    legend: string;
+    items: readonly T[];
+    /** Receives the next array after an add / remove / reorder / item edit. */
+    onChange: (next: T[]) => void;
+    /** Render one item's fields; `update` replaces that item in place. */
+    renderItem: (item: T, update: (next: T) => void, index: number) => React.ReactNode;
+    /** Factory for the entry appended by the Add button. */
+    createItem: () => T;
+    /** Stable React key per item. Defaults to the index. */
+    keyOf?: (item: T, index: number) => string;
+    /** Human label for an item, used in the item caption and button names. */
+    itemLabel: (item: T, index: number) => string;
+    addLabel?: string;
+    removeLabel?: string;
+    moveUpLabel?: string;
+    moveDownLabel?: string;
+    /** Shown when there are no items yet. */
+    emptyHint?: string;
+}
+/**
+ * Add / remove / reorder editor for a repeating array field (spec §14.2
+ * "リピーター"). Reordering uses keyboard-operable Move up / Move down buttons
+ * rather than drag-and-drop so the control meets WCAG 2.1 AA (spec §8.5)
+ * without a pointer.
+ */
+declare function Repeater<T>({ legend, items, onChange, renderItem, createItem, keyOf, itemLabel, addLabel, removeLabel, moveUpLabel, moveDownLabel, emptyHint, }: RepeaterProps<T>): React.JSX.Element;
+
+/**
+ * UI strings for the admin editor.
+ *
+ * The admin surface is operator-only, so a single English dictionary ships
+ * today; the lookup mirrors `getUILabel` (exact locale → base subtag →
+ * English) so locales can be added later without touching call sites. Keys are
+ * derived from the English dictionary, so every key is guaranteed to resolve.
+ */
+
+declare const EN: {
+    readonly 'app.title': "takuhon admin";
+    readonly 'toolbar.label': "Editor actions";
+    readonly 'mode.label': "Editing mode";
+    readonly 'mode.form': "Form";
+    readonly 'mode.advanced': "Advanced (JSON)";
+    readonly 'action.save': "Save";
+    readonly 'action.reload': "Reload";
+    readonly 'action.export': "Export";
+    readonly 'action.import': "Import";
+    readonly 'action.add': "Add";
+    readonly 'action.remove': "Remove";
+    readonly 'action.moveUp': "Move up";
+    readonly 'action.moveDown': "Move down";
+    readonly 'status.saving': "Saving…";
+    readonly 'status.saved': "Saved.";
+    readonly 'status.loading': "Loading…";
+    readonly 'status.conflict': "The profile changed on the server since it was loaded. Reload, then reapply the edits.";
+    readonly 'status.invalid': "Some fields need attention before saving.";
+    readonly 'status.fixSummary': "Please fix the following:";
+    readonly 'status.error': "Something went wrong. Please try again.";
+    readonly 'status.imported': "Imported. Review the fields, then save to apply.";
+    readonly 'status.importInvalid': "The imported file is not a valid takuhon document.";
+    readonly 'section.profile': "Profile";
+    readonly 'section.about': "About";
+    readonly 'section.links': "Links";
+    readonly 'section.careers': "Experience";
+    readonly 'section.projects': "Projects";
+    readonly 'section.skills': "Skills";
+    readonly 'section.settings': "Settings";
+    readonly 'field.displayName': "Display name";
+    readonly 'field.tagline': "Tagline";
+    readonly 'field.bio': "Bio";
+    readonly 'field.avatarUrl': "Avatar URL";
+    readonly 'field.avatarAlt': "Avatar alternative text";
+    readonly 'field.location.country': "Country";
+    readonly 'field.location.region': "Region";
+    readonly 'field.location.locality': "Locality";
+    readonly 'field.location.display': "Location (display)";
+    readonly 'field.link.type': "Type";
+    readonly 'field.link.url': "URL";
+    readonly 'field.link.label': "Label";
+    readonly 'field.link.iconUrl': "Icon URL";
+    readonly 'field.link.featured': "Featured";
+    readonly 'field.career.organization': "Organization";
+    readonly 'field.career.role': "Role";
+    readonly 'field.career.description': "Description";
+    readonly 'field.career.startDate': "Start";
+    readonly 'field.career.endDate': "End";
+    readonly 'field.career.isCurrent': "Current position";
+    readonly 'field.career.url': "URL";
+    readonly 'field.project.title': "Title";
+    readonly 'field.project.description': "Description";
+    readonly 'field.project.url': "URL";
+    readonly 'field.project.tags': "Tags";
+    readonly 'field.project.highlighted': "Highlighted";
+    readonly 'field.project.startDate': "Start";
+    readonly 'field.project.endDate': "End";
+    readonly 'field.skill.label': "Label";
+    readonly 'field.skill.category': "Category";
+    readonly 'field.settings.defaultLocale': "Default locale";
+    readonly 'field.settings.fallbackLocale': "Fallback locale";
+    readonly 'field.settings.availableLocales': "Available locales";
+    readonly 'field.settings.theme': "Theme";
+    readonly 'field.settings.showPoweredBy': "Show the \"Powered by takuhon\" footer";
+    readonly 'field.settings.enableJsonLd': "Emit Schema.org JSON-LD";
+    readonly 'field.settings.enableApi': "Expose the public read API";
+    readonly 'field.settings.enableAnalytics': "Enable first-party analytics";
+    readonly 'item.link': "Link";
+    readonly 'item.career': "Position";
+    readonly 'item.project': "Project";
+    readonly 'item.skill': "Skill";
+    readonly 'empty.links': "No links yet.";
+    readonly 'empty.careers': "No positions yet.";
+    readonly 'empty.projects': "No projects yet.";
+    readonly 'empty.skills': "No skills yet.";
+    readonly 'hint.avatarNoUpload': "Paste an image URL. Uploading image files is not available yet.";
+    readonly 'hint.month': "Format: YYYY-MM (e.g. 2024-03).";
+    readonly 'hint.country': "ISO 3166-1 alpha-2 code, e.g. US.";
+    readonly 'hint.tags': "Comma-separated.";
+    readonly 'hint.locales': "Comma-separated BCP-47 tags, e.g. en, ja. Drives the language tabs above.";
+    readonly 'advanced.hint': "Edit the entire document as JSON. Edits apply only while the JSON is valid.";
+    readonly 'advanced.invalid': "The JSON is not a valid takuhon document:";
+    readonly 'option.none': "(none)";
+};
+/** Every label key understood by {@link getAdminLabel}. */
+type AdminLabelKey = keyof typeof EN;
+/**
+ * Resolve an admin label for a locale, falling back to the base language
+ * subtag and then English. English is always present, so the return is always
+ * a string.
+ */
+declare function getAdminLabel(key: AdminLabelKey, locale?: LocaleTag): string;
+
+interface ProfileFormProps {
+    value: Profile;
+    onChange: (next: Profile) => void;
+    locales: readonly LocaleTag[];
+    errors?: FieldErrorIndex;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/**
+ * Basic profile + About: display name, tagline, bio, avatar URL, and a
+ * structured location (spec §6.5 / §14.2). Image upload is not wired yet, so
+ * the avatar is a URL field only.
+ */
+declare function ProfileForm({ value, onChange, locales, errors, formatLocale, }: ProfileFormProps): React.JSX.Element;
+
+interface LinksFormProps {
+    value: readonly Link[];
+    onChange: (next: Link[]) => void;
+    locales: readonly LocaleTag[];
+    errors?: FieldErrorIndex;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/** SNS / profile links with builtin-vs-custom typing (spec §6.6 / §14.2). */
+declare function LinksForm({ value, onChange, locales, errors, formatLocale, }: LinksFormProps): React.JSX.Element;
+
+interface CareersFormProps {
+    value: readonly Career[];
+    onChange: (next: Career[]) => void;
+    locales: readonly LocaleTag[];
+    errors?: FieldErrorIndex;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/** Work experience (spec §6.7 / §14.2 "職歴"). */
+declare function CareersForm({ value, onChange, locales, errors, formatLocale, }: CareersFormProps): React.JSX.Element;
+
+interface ProjectsFormProps {
+    value: readonly Project[];
+    onChange: (next: Project[]) => void;
+    locales: readonly LocaleTag[];
+    errors?: FieldErrorIndex;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/** Projects (spec §6.8 / §14.2). */
+declare function ProjectsForm({ value, onChange, locales, errors, formatLocale, }: ProjectsFormProps): React.JSX.Element;
+
+interface SkillsFormProps {
+    value: readonly Skill[];
+    onChange: (next: Skill[]) => void;
+    errors?: FieldErrorIndex;
+}
+/** Skills (spec §6.9 / §14.2). `label` is a plain string, not localized. */
+declare function SkillsForm({ value, onChange, errors, }: SkillsFormProps): React.JSX.Element;
+
+interface SettingsFormProps {
+    value: Settings;
+    onChange: (next: Settings) => void;
+    errors?: FieldErrorIndex;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/** Site settings: locales, theme, and feature toggles (spec §6.20 / §14.2). */
+declare function SettingsForm({ value, onChange, errors, formatLocale, }: SettingsFormProps): React.JSX.Element;
+
+interface RawJsonEditorProps {
+    value: Takuhon;
+    /** Called with the parsed document whenever the text is valid JSON + schema. */
+    onChange: (next: Takuhon) => void;
+}
+/**
+ * Advanced editing surface: the entire document as JSON text. Edits commit to
+ * the draft only when the text parses and passes schema validation, so the
+ * structured form view it shares state with never sees a malformed document.
+ * This is also the only way to edit sections without a dedicated form (spec
+ * §14.1 Phase 5 — JSON editor retained as the advanced mode).
+ */
+declare function RawJsonEditor({ value, onChange }: RawJsonEditorProps): React.JSX.Element;
+
+/** Result of a save attempt, reported by the host's transport layer. */
+type AdminSaveOutcome = {
+    status: 'saved';
+    version?: string;
+} | {
+    status: 'conflict';
+} | {
+    status: 'invalid';
+    errors: readonly FieldErrorLike[];
+} | {
+    status: 'error';
+    message?: string;
+};
+interface AdminEditorProps {
+    /** Document to edit, typically loaded from `GET /api/admin/export`. */
+    initialDocument: Takuhon;
+    /** Persist the document. The editor validates client-side first. */
+    onSave: (document: Takuhon) => Promise<AdminSaveOutcome>;
+    /** Re-fetch the stored document, replacing the working draft. */
+    onReload?: () => Promise<Takuhon>;
+    /** Download / hand off the current draft (Export button). */
+    onExport?: (document: Takuhon) => void;
+    /**
+     * Provide a document to load (Import button). Returns raw parsed JSON, which
+     * the editor validates; `undefined` cancels. Validation lives here so an
+     * invalid file cannot break the draft invariant.
+     */
+    onImport?: () => Promise<unknown>;
+    formatLocale?: (locale: LocaleTag) => string;
+}
+/**
+ * Top-level admin editor: holds the working draft, switches between the field
+ * forms and the raw-JSON advanced mode, and runs client-side validation before
+ * delegating persistence to the host via `onSave` (transport-agnostic). Server
+ * (RFC 7807) and client (`validate`) errors map to the same fields.
+ */
+declare function AdminEditor({ initialDocument, onSave, onReload, onExport, onImport, formatLocale, }: AdminEditorProps): React.JSX.Element;
+
+export { AdminEditor, type AdminEditorProps, type AdminLabelKey, type AdminSaveOutcome, CareersForm, type CareersFormProps, CheckboxField, type CheckboxFieldProps, Field, type FieldControlProps, type FieldErrorIndex, type FieldErrorLike, type FieldProps, LinksForm, type LinksFormProps, LocaleTabs, type LocaleTabsProps, NO_FIELD_ERRORS, ProfileForm, type ProfileFormProps, ProjectsForm, type ProjectsFormProps, RawJsonEditor, type RawJsonEditorProps, Repeater, type RepeaterProps, SelectField, type SelectFieldProps, type SelectOption, SettingsForm, type SettingsFormProps, SkillsForm, type SkillsFormProps, TextAreaField, type TextAreaFieldProps, TextField, type TextFieldProps, canonicalPointer, collectErrorsUnder, errorsAt, getAdminLabel, hasErrorsUnder, indexErrors, indexValidationErrors };