@karmicsoft/lc-schema 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+LightCode Platform License — Community, Educational, and Partnership Use
+© KarmicSoft. All rights reserved.
+
+This package (@karmicsoft/lc-schema) is part of the LightCode platform components
+developed by KarmicSoft (Erasmus+ project "Strengthening the Digital Transformation
+of Higher Education Through Low-Code", No. 2022-1-FR01-KA220-HED-000086863).
+
+Free access and use are granted for educational and non-commercial academic
+purposes, and for LightCode partner and collaboration projects. Use outside this
+scope — commercial activities, professional services, or proprietary integrations —
+requires a separate commercial agreement.
+
+Full terms: see licence.md in the lightcodepedia repository
+(https://lightcodepedia.org). Contact KarmicSoft for a partnership or commercial
+license.

package/README.md

@@ -0,0 +1,63 @@
+# @karmicsoft/lc-schema
+
+Schema → **neutral IR** → widget definitions — a small **schema compiler** and a
+**LightCode** brick. © KarmicSoft (see `LICENSE`).
+
+## Why (the SSOT strategy)
+
+Keep **one canonical schema** and generate the rest, instead of hand-maintaining
+several descriptions of the same model (which drift). `lc-schema` is the compiler:
+
+```
+  CANONICAL SOURCE ─(reader)→ neutral IR ─(consumers/emitters)→ { lc widgets · JSON Schema · config.yml · … }
+     (your choice)            (LightCode)
+```
+
+The **IR decouples the choice of canonical source**: switching Zod ↔ config.yml
+later changes only the *reader*; consumers (the editor) are unaffected — **reversible,
+no lock-in**.
+
+## Install
+
+```sh
+npm install @karmicsoft/lc-schema
+```
+
+## API (v0.1)
+
+```js
+import { fromSveltiaConfig, widgets, collections } from '@karmicsoft/lc-schema';
+
+const ir = fromSveltiaConfig(readFileSync('public/admin/config.yml', 'utf8'));
+collections(ir);            // ["persons", "events", ...]
+widgets(ir, 'persons');     // flat widget list the lc-editor renders
+```
+
+### Neutral IR shape
+
+```
+{ irVersion, source, collections: [
+  { name, label, folder, extension, identifier, fields: [ Field ] }
+]}
+Field = { name, label, widget, required, hint?, default?,
+          options?      // select: [{label, value}]
+          collection?, multiple?, valueField?, displayField?  // relation
+          item?         // list of scalars
+          fields?       // object / objectlist
+        }
+```
+
+Supported widgets: `string · text · number · boolean · select · relation · list ·
+objectlist · object · markdown · image · file · hidden`.
+
+## SSOT — canonical source, your call (reversible)
+
+- **v0.1 reader: Sveltia/Decap `config.yml`** (already in your repo).
+- **Recommended canonical: your Zod `content.config.ts`** — it is your build authority
+  and the richest (`reference()`, refinements, `nullSafe`, `dateStr`); `config.yml` is a
+  *subset*. With a Zod reader (roadmap), `config.yml` becomes **generated** and the
+  duplication disappears.
+- **If you keep `config.yml` canonical:** add a CI check that it stays consistent with
+  the Zod (which carries semantics `config.yml` can't).
+
+Either way, consumers read the **IR**, so the decision is reversible.

package/example.config.yml

@@ -0,0 +1,33 @@
+# Minimal Sveltia/Decap config excerpt — feed it to fromSveltiaConfig().
+collections:
+  - name: persons
+    label: Personnages
+    folder: content/persons
+    extension: yaml
+    identifier_field: title
+    fields:
+      - { name: title, label: Nom affiché, widget: string }
+      - { name: gender, label: Genre, widget: select, required: false,
+          options: [masculin, féminin, non-binaire, inconnu] }
+      - name: professions
+        label: Professions
+        widget: list
+        required: false
+        field: { name: profession, widget: string }
+      - name: periods
+        label: Époques
+        widget: relation
+        collection: periods
+        multiple: true
+        search_fields: [title]
+        value_field: '{{slug}}'
+        display_fields: [title]
+      - name: addresses
+        label: Adresses
+        widget: list
+        required: false
+        fields:
+          - { name: id, label: Adresse, widget: relation, collection: addresses,
+              value_field: '{{slug}}', display_fields: [title] }
+          - { name: role, label: Rôle, widget: string, required: false }
+      - { name: body, label: Biographie, widget: markdown }

package/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @karmicsoft/lc-schema — schema → neutral IR → widget definitions.
+ * © KarmicSoft — LightCode.
+ */
+
+export const IR_VERSION: string;
+
+export interface IROption { label: string; value: unknown; }
+
+export interface IRField {
+  name: string;
+  label: string;
+  /** string | text | number | boolean | select | relation | list | objectlist | object | markdown | image | file | hidden */
+  widget: string;
+  required?: boolean;
+  hint?: string;
+  default?: unknown;
+  /** select / relation */
+  multiple?: boolean;
+  /** select */
+  options?: IROption[];
+  /** relation */
+  collection?: string;
+  valueField?: string;
+  displayField?: string;
+  searchFields?: string[];
+  /** object / objectlist */
+  fields?: IRField[];
+  /** list of scalars */
+  item?: IRField;
+}
+
+export interface IRCollection {
+  name: string;
+  label: string;
+  folder?: string;
+  extension?: string;
+  identifier?: string;
+  slug?: string;
+  fields: IRField[];
+}
+
+export interface IR {
+  irVersion: string;
+  source: string;
+  collections: IRCollection[];
+}
+
+/** Compile a Sveltia/Decap config.yml (string or parsed object) into the neutral IR. */
+export function fromSveltiaConfig(config: string | object): IR;
+
+/** The flat field list for one collection (throws if the collection is unknown). */
+export function widgets(ir: IR, collectionName: string): IRField[];
+
+/** All collection names in the IR. */
+export function collections(ir: IR): string[];

package/index.js

@@ -0,0 +1,85 @@
+/*!
+ * @karmicsoft/lc-schema — schema → neutral IR → widget definitions.
+ * © KarmicSoft — LightCode. See LICENSE.
+ *
+ * SSOT strategy: keep ONE canonical schema and generate the rest. This is a
+ * small "schema compiler": a reader turns your canonical source into a neutral
+ * IR; the lc-* editor (and other back-ends) consume the IR. Swapping the
+ * canonical source later changes only the reader — consumers are unaffected.
+ *
+ * v0.1 ships the Sveltia/Decap `config.yml` reader (config is already in your
+ * repo). A Zod reader + projections (config.yml, JSON Schema) can be added
+ * without touching consumers — see README § SSOT.
+ */
+import yaml from 'js-yaml';
+
+export const IR_VERSION = '0.1';
+
+// Sveltia/Decap widget → neutral IR widget.
+const WIDGET = {
+  string: 'string', text: 'text', number: 'number', boolean: 'boolean',
+  select: 'select', relation: 'relation', list: 'list', object: 'object',
+  markdown: 'markdown', image: 'image', file: 'file', hidden: 'hidden',
+  datetime: 'string', code: 'text',
+};
+
+/** Parse a Sveltia/Decap config.yml (string or object) into the neutral IR. */
+export function fromSveltiaConfig(config) {
+  const cfg = typeof config === 'string' ? yaml.load(config, { schema: yaml.CORE_SCHEMA }) : config;
+  if (!cfg || !Array.isArray(cfg.collections)) throw new Error('lc-schema: not a Sveltia/Decap config (missing collections[])');
+  return { irVersion: IR_VERSION, source: 'sveltia', collections: cfg.collections.map(mapCollection) };
+}
+
+function mapCollection(c) {
+  return {
+    name: c.name,
+    label: c.label || c.name,
+    folder: c.folder,
+    extension: c.extension || 'yaml',
+    identifier: c.identifier_field || 'title',
+    slug: c.slug,
+    fields: (c.fields || []).map(mapField),
+  };
+}
+
+function mapField(f) {
+  let w = WIDGET[f.widget] || 'string';
+  const out = { name: f.name, label: f.label || prettify(f.name), widget: w };
+  out.required = f.required !== false;
+  if (f.hint) out.hint = f.hint;
+  if (f.default !== undefined) out.default = f.default;
+
+  if (w === 'select') {
+    out.multiple = !!f.multiple;
+    out.options = (f.options || []).map((o) =>
+      (o && typeof o === 'object') ? { label: o.label ?? String(o.value), value: o.value }
+                                   : { label: String(o), value: o });
+  } else if (w === 'relation') {
+    out.collection = f.collection;
+    out.multiple = !!f.multiple;
+    out.valueField = f.value_field || '{{slug}}';
+    out.displayField = firstOf(f.display_fields) || firstOf(f.search_fields) || 'title';
+    out.searchFields = asArray(f.search_fields);
+  } else if (w === 'list') {
+    if (Array.isArray(f.fields)) { out.widget = 'objectlist'; out.fields = f.fields.map(mapField); }
+    else out.item = f.field ? mapField(f.field) : { name: 'value', widget: 'string' };
+  } else if (w === 'object') {
+    out.fields = (f.fields || []).map(mapField);
+  }
+  return out;
+}
+
+/** Flat widget list for the editor, for one collection. */
+export function widgets(ir, collectionName) {
+  const c = ir.collections.find((c) => c.name === collectionName);
+  if (!c) throw new Error(`lc-schema: unknown collection "${collectionName}"`);
+  return c.fields;
+}
+
+/** All collection names in the IR. */
+export function collections(ir) { return ir.collections.map((c) => c.name); }
+
+const isArr = Array.isArray;
+function firstOf(a) { return isArr(a) ? a[0] : a; }
+function asArray(a) { return isArr(a) ? a : (a == null ? [] : [a]); }
+function prettify(s) { return String(s || '').replace(/[-_]/g, ' ').replace(/\b\w/g, (m) => m.toUpperCase()); }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@karmicsoft/lc-schema",
+  "version": "0.1.0",
+  "description": "Schema → neutral IR → widget definitions (schema compiler) — a LightCode brick.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "example.config.yml",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "KarmicSoft",
+  "homepage": "https://lightcodepedia.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michelzam/lightcodepedia",
+    "directory": "packages/lc-schema"
+  },
+  "dependencies": {
+    "js-yaml": "^4.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "schema",
+    "low-code",
+    "forms",
+    "sveltia",
+    "zod",
+    "lightcode",
+    "karmicsoft"
+  ]
+}