@takuhon/ui 0.24.0 → 0.25.0

package/dist/admin/index.d.ts

@@ -1,4 +1,4 @@
-import { ValidationError, LocaleTag, Profile, Link, Career, Project, Skill, Settings, Takuhon } from '@takuhon/core';
+import { ValidationError, LocaleTag, Takuhon } from '@takuhon/core';
 
 /**
  * Field-error plumbing shared by the admin form components.
@@ -295,6 +295,19 @@ declare const EN: {
     readonly 'section.projects': "Projects";
     readonly 'section.skills': "Skills";
     readonly 'section.settings': "Settings";
+    readonly 'section.education': "Education";
+    readonly 'section.certifications': "Certifications";
+    readonly 'section.publications': "Publications";
+    readonly 'section.honors': "Honors & awards";
+    readonly 'section.volunteering': "Volunteering";
+    readonly 'section.memberships': "Memberships";
+    readonly 'section.languages': "Languages";
+    readonly 'section.courses': "Courses";
+    readonly 'section.patents': "Patents";
+    readonly 'section.testScores': "Test scores";
+    readonly 'section.recommendations': "Recommendations";
+    readonly 'section.contact': "Contact";
+    readonly 'section.meta': "Metadata";
     readonly 'field.displayName': "Display name";
     readonly 'field.tagline': "Tagline";
     readonly 'field.bio': "Bio";
@@ -382,71 +395,241 @@ type AdminLabelKey = keyof typeof EN;
  */
 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;
-    /**
-     * Upload an avatar image file. When provided, the avatar field offers a file
-     * picker; when omitted, it stays URL-only.
-     */
-    uploadAsset?: UploadAsset;
+/**
+ * Schema-driven field classification for the admin editor.
+ *
+ * Maps a node of the canonical takuhon JSON Schema (2020-12) to a
+ * {@link FieldKind} — the widget the admin form should render for it. This is
+ * the pure-logic foundation of the schema-driven form engine (design:
+ * `admin-form-schema-driven-design.md`). It resolves local `$ref`s against
+ * `$defs` and unwraps nullable `anyOf` unions, so the renderer never hand-wires
+ * fields per section. No React here; the classifier is fully unit-testable.
+ *
+ * Presentation concerns the schema cannot express (widget overrides, ordering,
+ * help text, cross-section reference selectors, image/Gravatar widgets) live in
+ * a separate field-spec registry, not in the data schema (design decision A1).
+ */
+/**
+ * Minimal structural view of a JSON Schema 2020-12 node — only the keywords the
+ * classifier reads. The canonical schema (`@takuhon/core`'s `schema`) is cast to
+ * this for traversal.
+ */
+interface SchemaNode {
+    $ref?: string;
+    $defs?: Record<string, SchemaNode>;
+    type?: string | readonly string[];
+    format?: string;
+    enum?: readonly unknown[];
+    properties?: Record<string, SchemaNode>;
+    required?: readonly string[];
+    items?: SchemaNode;
+    anyOf?: readonly SchemaNode[];
+    maxLength?: number;
+    minimum?: number;
+    description?: string;
+    default?: unknown;
 }
+/** The widget the admin form should render for a classified schema node. */
+type FieldKind = {
+    widget: 'text';
+    maxLength?: number;
+} | {
+    widget: 'url';
+} | {
+    widget: 'email';
+} | {
+    widget: 'month';
+} | {
+    widget: 'date';
+} | {
+    widget: 'datetime';
+} | {
+    widget: 'integer';
+    minimum?: number;
+} | {
+    widget: 'checkbox';
+    default?: boolean;
+} | {
+    widget: 'select';
+    options: readonly string[];
+} | {
+    widget: 'localeTag';
+} | {
+    widget: 'localizedTitle';
+} | {
+    widget: 'localizedBody';
+} | {
+    widget: 'slug';
+} | {
+    widget: 'array';
+    item: FieldKind;
+} | {
+    widget: 'object';
+    fields: readonly FieldEntry[];
+} | {
+    widget: 'unsupported';
+};
+/** A named property of an object schema: its optionality and classified kind. */
+interface FieldEntry {
+    name: string;
+    /** Listed in the object's `required` array. */
+    required: boolean;
+    /** The schema permits an explicit `null` (e.g. `anyOf: [X, { type: 'null' }]`). */
+    nullable: boolean;
+    kind: FieldKind;
+}
+/** Classify a (possibly `$ref`/nullable) schema node into the widget to render. */
+declare function classifyNode(root: SchemaNode, node: SchemaNode): FieldKind;
+/** Classify a top-level section (e.g. `'education'`, `'contact'`) by name. */
+declare function sectionFieldKind(root: SchemaNode, section: string): FieldKind;
+
 /**
- * Basic profile + About: display name, tagline, bio, avatar, and a structured
- * location (spec §6.5 / §14.2). The avatar accepts a URL and, when
- * `uploadAsset` is supplied by the host, an uploaded image file.
+ * Field-spec registry — the UI-hint layer the data schema deliberately does not
+ * carry (design decision A1). Keyed by a section-relative dot path *without*
+ * array indices (e.g. `education.institution`, `meta.createdAt`), it overrides
+ * or augments the schema-derived classification with presentation concerns:
+ * labels, help text, hiding auto-managed fields, forcing a widget.
+ *
+ * Keeping these out of `takuhon.schema.json` leaves the data contract pure
+ * (consumers / validators see no UI noise) and means this track changes no
+ * `schemaVersion`.
  */
-declare function ProfileForm({ value, onChange, locales, errors, formatLocale, uploadAsset, }: ProfileFormProps): React.JSX.Element;
 
-interface LinksFormProps {
-    value: readonly Link[];
-    onChange: (next: Link[]) => void;
+/**
+ * Everything a custom field renderer needs. The engine builds this as it walks,
+ * so a bespoke widget (avatar, comma-separated list, visibility matrix) plugs in
+ * without re-deriving its pointer/path or re-threading locales and errors. This
+ * is the escape hatch for the handful of fields a generic widget cannot capture
+ * (design §8 "generic default + targeted craft").
+ */
+interface CustomFieldContext {
+    /** Current value at this path. */
+    value: unknown;
+    /** Write the next value for this field back into the document. */
+    onChange: (next: unknown) => void;
+    /** RFC 6901 pointer (with array indices) for error lookup. */
+    pointer: string;
+    /** Registry path (no array indices). */
+    path: string;
+    /** Resolved label (registry override or humanized field name). */
+    label: string;
+    /** Listed in the parent object's `required`. */
+    required: boolean;
     locales: readonly LocaleTag[];
-    errors?: FieldErrorIndex;
+    errors: FieldErrorIndex;
     formatLocale?: (locale: LocaleTag) => string;
+    /** Avatar upload, threaded from the host; absent means URL-only. */
+    uploadAsset?: UploadAsset;
+    /**
+     * The whole document (root value), so a field can read sibling sections —
+     * e.g. a reference selector listing `careers[]` / `education[]` ids. Typed
+     * `unknown` to keep the engine schema-generic; renderers narrow it.
+     */
+    document?: unknown;
 }
-/** 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;
+/** Presentation overrides for a single field, looked up by its schema path. */
+interface FieldHint {
+    /** Replace the humanized field name. */
+    label?: string;
+    /** Help text shown under the control. */
+    hint?: string;
+    /** Omit from the form (the value is still preserved in the document). */
+    hidden?: boolean;
+    /** Render this widget instead of the schema-derived one. */
+    widget?: FieldKind['widget'];
+    /** Force multiline for a localized/text field. */
+    multiline?: boolean;
+    /**
+     * Render a bespoke control for this field instead of the schema-derived
+     * widget. Used for the few fields no generic widget captures (avatar,
+     * comma-separated lists, the public-visibility matrix).
+     */
+    render?: (ctx: CustomFieldContext) => React.ReactNode;
 }
-/** Work experience (spec §6.7 / §14.2 "職歴"). */
-declare function CareersForm({ value, onChange, locales, errors, formatLocale, }: CareersFormProps): React.JSX.Element;
+/** Schema-path → hint. Paths use dots and never include array indices. */
+type FieldRegistry = Readonly<Record<string, FieldHint>>;
+declare const EMPTY_REGISTRY: FieldRegistry;
+/**
+ * Humanize a property name for a default label: `fieldOfStudy` → `Field of
+ * study`, `credentialId` → `Credential ID`, `url` → `URL`. Known acronyms stay
+ * uppercased. The registry overrides this where a better label is needed.
+ */
+declare function humanize(name: string): string;
+/** The hint at `path`, or an empty hint when none is registered. */
+declare function hintAt(registry: FieldRegistry, path: string): FieldHint;
+
+/**
+ * Schema-driven form engine.
+ *
+ * Renders an editable form for any takuhon section straight from its
+ * {@link FieldKind} (see `field-classification.ts`), using the existing admin
+ * primitives. The RFC 6901 `pointer` (with array indices, for error lookup) and
+ * the registry `path` (without indices, for UI hints) are derived automatically
+ * as the engine walks — so no section hand-wires field plumbing or pointer
+ * strings. Presentation overrides come from the {@link FieldRegistry}
+ * (decision A1); the data schema stays UI-free.
+ *
+ * Values are treated as `unknown` and narrowed per kind — the document has been
+ * (or will be) validated against the schema, so each branch's cast is sound.
+ */
 
-interface ProjectsFormProps {
-    value: readonly Project[];
-    onChange: (next: Project[]) => void;
+interface SchemaFormProps {
+    /** Classified shape of the section (from `sectionFieldKind`). */
+    kind: FieldKind;
+    /** Current value for the section. */
+    value: unknown;
+    /** Receives the next value on any edit. */
+    onChange: (next: unknown) => void;
+    /** RFC 6901 pointer to this value, e.g. `/education`. */
+    pointer: string;
+    /** Registry path (no array indices). Defaults to the pointer sans leading slash. */
+    path?: string;
+    /** Heading for the section / object. */
+    label: string;
     locales: readonly LocaleTag[];
     errors?: FieldErrorIndex;
+    registry?: FieldRegistry;
     formatLocale?: (locale: LocaleTag) => string;
+    /** Avatar upload, threaded to the avatar field's custom renderer. */
+    uploadAsset?: UploadAsset;
+    /** Whole document, so reference fields can list sibling-section ids. */
+    document?: unknown;
 }
-/** Projects (spec §6.8 / §14.2). */
-declare function ProjectsForm({ value, onChange, locales, errors, formatLocale, }: ProjectsFormProps): React.JSX.Element;
+/**
+ * Render a section's form from its schema-derived {@link FieldKind}. Array
+ * sections become a {@link Repeater}; object sections a labelled fieldset;
+ * scalars map to the matching primitive.
+ */
+declare function SchemaForm(props: SchemaFormProps): 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;
+/**
+ * The admin editor's single source of truth for which sections to render and how.
+ *
+ * {@link ADMIN_SECTIONS} lists every top-level section in display order; the
+ * {@link SchemaForm} engine renders each one from the schema. {@link SECTION_REGISTRY}
+ * is the UI-hint layer (decision A1): bespoke renderers for the few fields a
+ * generic widget cannot capture (avatar, comma-separated lists, the visibility
+ * matrix), plus curated labels and help text. The data schema stays UI-free.
+ */
 
-interface SettingsFormProps {
-    value: Settings;
-    onChange: (next: Settings) => void;
-    errors?: FieldErrorIndex;
-    formatLocale?: (locale: LocaleTag) => string;
+interface AdminSection {
+    key: keyof Takuhon;
+    label: AdminLabelKey;
 }
-/** Site settings: locales, theme, and feature toggles (spec §6.20 / §14.2). */
-declare function SettingsForm({ value, onChange, errors, formatLocale, }: SettingsFormProps): React.JSX.Element;
+/**
+ * All editable sections, in display order. The first six were once bespoke
+ * forms; they now share the schema-driven engine with the rest, so every section
+ * is a form (spec §14.2 Phase 5, no more raw-JSON-only sections).
+ */
+declare const ADMIN_SECTIONS: readonly AdminSection[];
+/**
+ * UI hints keyed by section-relative dot path (no array indices). Covers the
+ * bespoke widgets (avatar, comma-separated lists, visibility matrix, and
+ * cross-section reference selectors), curated labels for fields whose humanized
+ * name reads poorly, help text, and the auto-managed meta fields that stay
+ * hidden.
+ */
+declare const SECTION_REGISTRY: FieldRegistry;
 
 interface RawJsonEditorProps {
     value: Takuhon;
@@ -506,4 +689,4 @@ interface AdminEditorProps {
  */
 declare function AdminEditor({ initialDocument, onSave, onReload, onExport, onImport, formatLocale, uploadAsset, }: AdminEditorProps): React.JSX.Element;
 
-export { AdminEditor, type AdminEditorProps, type AdminLabelKey, type AdminSaveOutcome, type AssetUploadResult, CareersForm, type CareersFormProps, CheckboxField, type CheckboxFieldProps, Field, type FieldControlProps, type FieldErrorIndex, type FieldErrorLike, type FieldProps, GravatarField, type GravatarFieldProps, ImageField, type ImageFieldProps, 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, type UploadAsset, canonicalPointer, collectErrorsUnder, errorsAt, getAdminLabel, hasErrorsUnder, indexErrors, indexValidationErrors };
+export { ADMIN_SECTIONS, AdminEditor, type AdminEditorProps, type AdminLabelKey, type AdminSaveOutcome, type AdminSection, type AssetUploadResult, CheckboxField, type CheckboxFieldProps, type CustomFieldContext, EMPTY_REGISTRY, Field, type FieldControlProps, type FieldErrorIndex, type FieldErrorLike, type FieldHint, type FieldKind, type FieldProps, type FieldRegistry, GravatarField, type GravatarFieldProps, ImageField, type ImageFieldProps, LocaleTabs, type LocaleTabsProps, NO_FIELD_ERRORS, RawJsonEditor, type RawJsonEditorProps, Repeater, type RepeaterProps, SECTION_REGISTRY, SchemaForm, type SchemaFormProps, type SchemaNode, SelectField, type SelectFieldProps, type SelectOption, TextAreaField, type TextAreaFieldProps, TextField, type TextFieldProps, type UploadAsset, canonicalPointer, classifyNode, collectErrorsUnder, errorsAt, getAdminLabel, hasErrorsUnder, hintAt, humanize, indexErrors, indexValidationErrors, sectionFieldKind };