@localess/schema 4.0.0-dev.20260905071322 → 4.0.0-dev.20260905083404

package/SKILL.md

@@ -63,7 +63,7 @@ export type Content = InferContentData<typeof config>;
 | Export | Purpose |
 |---|---|
 | `defineEnum(definition)` | Define an ENUM schema. Identity function; injects `type: 'ENUM'`. |
-| `defineSchema(definition)` | Define a ROOT or NODE schema. Normalizes by-value refs (`source`, `schemas`) to id strings. Throws on duplicate field names. |
+| `defineSchema(definition)` | Define a ROOT or NODE schema. Normalizes by-value refs (`source`, `schemas`) to id strings. Throws on duplicate field names. `previewField` is restricted to the names of the schema's own `fields` (falls back to `string` when `fields` is omitted). |
 | `defineField(field)` | Define a single field, narrowed by `kind`. Optional; catches a stray property from the wrong kind at the call site, unlike a bare field literal. Identity function. |
 | `defineConfig({ schemas })` | Register the full schema list — the unit the CLI loads and inference resolves against. Throws on duplicate schema ids. |
 | `validate(config)` | Non-throwing `{ ok, issues }` — ID/name patterns, reserved names, length limits, reference resolution. |

package/dist/define.d.ts

@@ -100,8 +100,21 @@ type DefinedComponent<TId extends string, TType extends 'ROOT' | 'NODE', TFields
  * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
  * exists to preserve literal types for inference.
  *
+ * - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+ * - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+ *   every `value` across the config becomes part of `InferEnum`'s literal union
+ *
  * @param definition the enum definition (id, values, optional display metadata)
  * @returns the definition with `type: 'ENUM'`, literal types preserved
+ *
+ * @example
+ * const Status = defineEnum({
+ *   id: 'Status',
+ *   values: [
+ *     { name: 'Draft', value: 'draft' },
+ *     { name: 'Published', value: 'published' },
+ *   ],
+ * });
  */
 export declare function defineEnum<const TId extends string, const TValues extends readonly SchemaEnumValue[] | undefined = undefined>(definition: {
     id: TId;
@@ -119,8 +132,29 @@ export declare function defineEnum<const TId extends string, const TValues exten
  * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
  * of a field's origin. See `docs/decisions/008-schema-package.md`.
  *
+ * Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+ * `defaultValue?`, `translatable?`. Kind-specific extras:
+ * - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+ * - `NUMBER` — `minValue?`, `maxValue?`
+ * - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+ * - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+ * - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+ * - `REFERENCE` / `REFERENCES` — `path?`
+ * - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+ * - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+ *   every `NODE` schema in the config is allowed when omitted)
+ *
+ * Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+ *
  * @param field the field definition; `kind` selects which extra properties are allowed
  * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+ *
+ * @example
+ * defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+ * @example
+ * defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+ * @example
+ * defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
  */
 export declare function defineField<const TKind extends SchemaFieldKind, const TName extends string, const TField extends Omit<Extract<SchemaFieldInput, {
     kind: TKind;
@@ -133,14 +167,36 @@ export declare function defineField<const TKind extends SchemaFieldKind, const T
     name: TName;
     kind: TKind;
 } & TField>;
+/** Union of a schema's own field names; falls back to plain `string` when `fields` is omitted. */
+type FieldNameOf<TFields> = TFields extends readonly {
+    name: infer N extends string;
+}[] ? N : string;
 /**
  * Define a ROOT (content type) or NODE (nested component) schema.
  * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
  * the returned type keeps those ids as literals for inference.
  *
+ * - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+ *   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+ * - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+ *   through another schema's `SCHEMA`/`SCHEMAS` field
+ * - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+ *   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+ *   when `fields` is omitted)
+ * - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+ *   `defineField` for the per-kind property reference
+ *
  * @param definition the schema definition; `type` selects ROOT or NODE
  * @returns the definition with references normalized to id strings, literal types preserved
  * @throws Error on duplicate field names — a programming error, not a validation concern
+ *
+ * @example
+ * const Button = defineSchema({
+ *   id: 'Button',
+ *   type: 'NODE',
+ *   previewField: 'label',
+ *   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+ * });
  */
 export declare function defineSchema<const TId extends string, const TType extends 'ROOT' | 'NODE', const TFields extends readonly SchemaFieldInput[] | undefined = undefined>(definition: {
     id: TId;
@@ -148,7 +204,7 @@ export declare function defineSchema<const TId extends string, const TType exten
     displayName?: string;
     description?: string;
     labels?: readonly string[];
-    previewField?: string;
+    previewField?: FieldNameOf<TFields>;
     fields?: TFields;
 }): DefinedComponent<TId, TType, TFields>;
 /**

package/dist/index.js

@@ -4,8 +4,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
 * exists to preserve literal types for inference.
 *
+* - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+* - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+*   every `value` across the config becomes part of `InferEnum`'s literal union
+*
 * @param definition the enum definition (id, values, optional display metadata)
 * @returns the definition with `type: 'ENUM'`, literal types preserved
+*
+* @example
+* const Status = defineEnum({
+*   id: 'Status',
+*   values: [
+*     { name: 'Draft', value: 'draft' },
+*     { name: 'Published', value: 'published' },
+*   ],
+* });
 */
 function defineEnum(definition) {
 	return {
@@ -22,8 +35,29 @@ function defineEnum(definition) {
 * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
 * of a field's origin. See `docs/decisions/008-schema-package.md`.
 *
+* Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+* `defaultValue?`, `translatable?`. Kind-specific extras:
+* - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+* - `NUMBER` — `minValue?`, `maxValue?`
+* - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+* - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+* - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+* - `REFERENCE` / `REFERENCES` — `path?`
+* - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+* - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+*   every `NODE` schema in the config is allowed when omitted)
+*
+* Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+*
 * @param field the field definition; `kind` selects which extra properties are allowed
 * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+*
+* @example
+* defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+* @example
+* defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+* @example
+* defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
 */
 function defineField(field) {
 	return field;
@@ -33,9 +67,27 @@ function defineField(field) {
 * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
 * the returned type keeps those ids as literals for inference.
 *
+* - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+*   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+* - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+*   through another schema's `SCHEMA`/`SCHEMAS` field
+* - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+*   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+*   when `fields` is omitted)
+* - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+*   `defineField` for the per-kind property reference
+*
 * @param definition the schema definition; `type` selects ROOT or NODE
 * @returns the definition with references normalized to id strings, literal types preserved
 * @throws Error on duplicate field names — a programming error, not a validation concern
+*
+* @example
+* const Button = defineSchema({
+*   id: 'Button',
+*   type: 'NODE',
+*   previewField: 'label',
+*   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+* });
 */
 function defineSchema(definition) {
 	const seen = /* @__PURE__ */ new Set();

package/dist/index.mjs

@@ -3,8 +3,21 @@
 * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
 * exists to preserve literal types for inference.
 *
+* - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+* - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+*   every `value` across the config becomes part of `InferEnum`'s literal union
+*
 * @param definition the enum definition (id, values, optional display metadata)
 * @returns the definition with `type: 'ENUM'`, literal types preserved
+*
+* @example
+* const Status = defineEnum({
+*   id: 'Status',
+*   values: [
+*     { name: 'Draft', value: 'draft' },
+*     { name: 'Published', value: 'published' },
+*   ],
+* });
 */
 function defineEnum(definition) {
 	return {
@@ -21,8 +34,29 @@ function defineEnum(definition) {
 * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
 * of a field's origin. See `docs/decisions/008-schema-package.md`.
 *
+* Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+* `defaultValue?`, `translatable?`. Kind-specific extras:
+* - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+* - `NUMBER` — `minValue?`, `maxValue?`
+* - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+* - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+* - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+* - `REFERENCE` / `REFERENCES` — `path?`
+* - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+* - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+*   every `NODE` schema in the config is allowed when omitted)
+*
+* Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+*
 * @param field the field definition; `kind` selects which extra properties are allowed
 * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+*
+* @example
+* defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+* @example
+* defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+* @example
+* defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
 */
 function defineField(field) {
 	return field;
@@ -32,9 +66,27 @@ function defineField(field) {
 * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
 * the returned type keeps those ids as literals for inference.
 *
+* - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+*   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+* - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+*   through another schema's `SCHEMA`/`SCHEMAS` field
+* - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+*   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+*   when `fields` is omitted)
+* - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+*   `defineField` for the per-kind property reference
+*
 * @param definition the schema definition; `type` selects ROOT or NODE
 * @returns the definition with references normalized to id strings, literal types preserved
 * @throws Error on duplicate field names — a programming error, not a validation concern
+*
+* @example
+* const Button = defineSchema({
+*   id: 'Button',
+*   type: 'NODE',
+*   previewField: 'label',
+*   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+* });
 */
 function defineSchema(definition) {
 	const seen = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/schema",
-  "version": "4.0.0-dev.20260905071322",
+  "version": "4.0.0-dev.20260905083404",
   "description": "Programmatic schema definitions for Localess with TypeScript content type inference.",
   "keywords": [
     "localess",
@@ -43,7 +43,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@localess/model": "4.0.0-dev.20260905071322"
+    "@localess/model": "4.0.0-dev.20260905083404"
   },
   "devDependencies": {
     "@types/node": "^24",