@owlmeans/viable-common 0.0.4

package/src/scaffold/schemas.ts

@@ -0,0 +1,283 @@
+import type { JSONSchemaType } from 'ajv'
+
+import { ProjectArea } from '../areas/consts.js'
+import { WidgetKind } from './consts.js'
+import type {
+  GuestHomePlan, ProductIdentity, ScaffoldAreaPlan, ScaffoldPlan, ScaffoldStoryPlan, SketchContent,
+} from './types.js'
+
+const SketchContentSchema: JSONSchemaType<SketchContent> = {
+  type: 'object',
+  title: 'SketchContent',
+  description: 'Plausible placeholder content for one drawn widget',
+  properties: {
+    headline: { type: 'string', description: "The placeholder's own heading, 2-5 words" },
+    caption: {
+      type: 'string',
+      description: 'One short line saying what the finished widget will show'
+    },
+    items: {
+      type: 'array', nullable: true,
+      items: { type: 'string' },
+      description: '3-5 example rows for a list widget - realistic record titles, never lorem ipsum'
+    },
+    columns: {
+      type: 'array', nullable: true,
+      items: { type: 'string' },
+      description: '3-5 column names for a table widget'
+    },
+    fields: {
+      type: 'array', nullable: true,
+      items: { type: 'string' },
+      description: '3-5 field labels for a form widget'
+    },
+    series: {
+      type: 'array', nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          label: { type: 'string', description: 'Short bar label' },
+          value: {
+            type: 'integer', minimum: 5, maximum: 100,
+            description: 'Relative bar height 5-100. Illustrative only, never real data'
+          },
+        },
+        required: ['label', 'value'],
+        additionalProperties: false,
+      },
+      description: '4-6 bars for a chart widget'
+    },
+    stats: {
+      type: 'array', nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          label: { type: 'string', description: 'What the figure counts' },
+          value: { type: 'string', description: 'A short illustrative figure, e.g. "128" or "94%"' },
+        },
+        required: ['label', 'value'],
+        additionalProperties: false,
+      },
+      description: '2-4 headline figures for a summary widget'
+    },
+  },
+  required: ['headline', 'caption'],
+  additionalProperties: false,
+}
+
+const ScaffoldStoryPlanSchema: JSONSchemaType<ScaffoldStoryPlan> = {
+  type: 'object',
+  title: 'ScaffoldStoryPlan',
+  description: 'Where one user story lives in the menus, and what its dashboard widget shows',
+  properties: {
+    code: {
+      type: 'string',
+      description: 'The story code, copied EXACTLY from the story list given to you'
+    },
+    section: {
+      type: 'string',
+      description: 'Top-menu section inside the story\'s own area, 1-2 words, Title Case.'
+        + ' Stories that an actor works on together share one section'
+    },
+    screen: {
+      type: 'string',
+      description: 'The main screen this story will need, named "{section}/{purpose}" -'
+        + ' e.g. "Requests/Submit a request". The section part must equal the section above'
+    },
+    widget: {
+      type: 'object',
+      properties: {
+        kind: {
+          type: 'string',
+          enum: Object.values(WidgetKind),
+          description: 'What shape this story\'s dashboard widget takes:'
+            + ' list (records one after another), table (records in columns),'
+            + ' form (the actor submits something), chart (a trend or comparison),'
+            + ' stat (headline figures)'
+        },
+        title: { type: 'string', description: 'The widget\'s title, 2-4 words' },
+        description: {
+          type: 'string',
+          description: 'One sentence on what the finished widget shows its actor'
+        },
+      },
+      required: ['kind', 'title', 'description'],
+      additionalProperties: false,
+    },
+    sketch: SketchContentSchema,
+    home: {
+      type: 'boolean',
+      description: 'Whether this widget is one of the few important enough to also appear on the'
+        + ' home screen of its area. At most 3 per area'
+    },
+    sharesWidgetWith: {
+      type: 'string', nullable: true,
+      description: 'OPTIONAL. The code of an EARLIER story in this list whose widget this story'
+        + ' renders instead of drawing its own. Set it only when the two act on the same record'
+        + ' through the same shape — the same form, the same table — so one preview honestly'
+        + ' stands for both. Omit it whenever they differ.',
+    },
+    sharesScreenWith: {
+      type: 'string', nullable: true,
+      description: 'OPTIONAL. The code of an EARLIER story in this list whose screen this story'
+        + ' shares. Use it only when the two steps genuinely happen on one page.',
+    },
+  },
+  required: ['code', 'section', 'screen', 'widget', 'sketch', 'home'],
+  additionalProperties: false,
+}
+
+const ScaffoldAreaPlanSchema: JSONSchemaType<ScaffoldAreaPlan> = {
+  type: 'object',
+  title: 'ScaffoldAreaPlan',
+  description: 'One area of the application: its menu sections and how it introduces itself',
+  properties: {
+    area: {
+      type: 'string',
+      enum: Object.values(ProjectArea),
+      description: 'guest, user, admin or operator'
+    },
+    intro: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'What this area is, 2-5 words' },
+        text: {
+          type: 'string',
+          description: 'Two sentences telling this area\'s actor what they can do here'
+        },
+      },
+      required: ['title', 'text'],
+      additionalProperties: false,
+    },
+    sections: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'The top-menu sections of this area, in menu order.'
+        + ' Every section named by a story of this area must appear here'
+    },
+  },
+  required: ['area', 'intro', 'sections'],
+  additionalProperties: false,
+}
+
+const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
+  type: 'object',
+  title: 'GuestHomePlan',
+  description: "The product's public landing page",
+  properties: {
+    hero: {
+      type: 'object',
+      properties: {
+        eyebrow: { type: 'string', description: 'A 2-4 word positioning phrase above the headline' },
+        headline: {
+          type: 'string',
+          description: 'The product\'s promise in one line, under 9 words. Never the product name alone'
+        },
+        sub: { type: 'string', description: 'One or two sentences: what it does and who it is for' },
+        cta: { type: 'string', description: 'The call-to-action label, 2-3 words' },
+      },
+      required: ['eyebrow', 'headline', 'sub', 'cta'],
+      additionalProperties: false,
+    },
+    problem: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'The problem in 3-6 words' },
+        text: {
+          type: 'string',
+          description: 'Two sentences on what is hard or slow today, from the point of view of'
+            + ' the person it happens to'
+        },
+      },
+      required: ['title', 'text'],
+      additionalProperties: false,
+    },
+    solution: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'How this product solves it, 3-6 words' },
+        text: { type: 'string', description: 'Two sentences on what changes once they use it' },
+      },
+      required: ['title', 'text'],
+      additionalProperties: false,
+    },
+    features: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'The capability, 2-4 words' },
+          text: { type: 'string', description: 'One sentence on what it lets someone do' },
+        },
+        required: ['title', 'text'],
+        additionalProperties: false,
+      },
+      description: '3 to 6 capabilities, taken from what the specification actually describes'
+    },
+    testimonials: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          quote: { type: 'string', description: 'One or two sentences a satisfied user would say' },
+          name: { type: 'string', description: 'A plausible first name and surname initial' },
+          role: { type: 'string', description: 'Their role, 2-4 words' },
+        },
+        required: ['quote', 'name', 'role'],
+        additionalProperties: false,
+      },
+      description: '2 or 3 illustrative testimonials'
+    },
+  },
+  required: ['hero', 'problem', 'solution', 'features', 'testimonials'],
+  additionalProperties: false,
+}
+
+export const ProductIdentitySchema: JSONSchemaType<ProductIdentity> = {
+  type: 'object',
+  title: 'ProductIdentity',
+  description: 'What this application calls itself wherever a machine reads it',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'The product\'s own name as a person reads it — two or three words, the name'
+        + ' the landing page uses. Never a slug, never a placeholder, never the word "App"'
+    },
+    description: {
+      type: 'string',
+      description: 'ONE sentence saying what this product is and who it is for, as a search'
+        + ' result or a browser tab would show it. Under 160 characters'
+    },
+  },
+  required: ['name', 'description'],
+  additionalProperties: false,
+}
+
+export const ScaffoldPlanSchema: JSONSchemaType<ScaffoldPlan> = {
+  type: 'object',
+  title: 'ScaffoldPlan',
+  description: 'The whole application, sketched: its landing page, its menus, and one drawn'
+    + ' widget per user story',
+  properties: {
+    identity: ProductIdentitySchema,
+    guestHome: GuestHomePlanSchema,
+    areas: {
+      type: 'array',
+      items: ScaffoldAreaPlanSchema,
+      description: 'One entry per area that has at least one user story, plus guest'
+    },
+    stories: {
+      type: 'array',
+      items: ScaffoldStoryPlanSchema,
+      description: 'EXACTLY one entry per user story given to you, in the same order'
+    },
+    motifs: {
+      type: 'string',
+      description: 'Two or three sentences directing this product\'s illustrations: what shapes'
+        + ' and subjects belong to it, in the design system\'s own vocabulary. Abstract geometry,'
+        + ' never a described photograph'
+    },
+  },
+  required: ['identity', 'guestHome', 'areas', 'stories', 'motifs'],
+  additionalProperties: false,
+}

package/src/scaffold/types.ts

@@ -0,0 +1,118 @@
+import type { ProjectArea } from '../areas/consts.js'
+import type { WidgetKind } from './consts.js'
+
+/**
+ * The placeholder content of one drawn widget.
+ *
+ * Structured rather than free text because the scaffold STAMPS these into code without a model:
+ * a paragraph describing a table cannot be turned into columns deterministically, a list of
+ * column names can.
+ */
+export interface SketchContent {
+  /** The heading the placeholder carries. */
+  headline: string
+  /** One line under it saying what the finished thing will show. */
+  caption: string
+  /** Example rows, for a list. */
+  items?: string[]
+  /** Column names, for a table. */
+  columns?: string[]
+  /** Field labels, for a form. */
+  fields?: string[]
+  /** Bars, for a chart — `value` is a 0..100 magnitude, not real data. */
+  series?: { label: string, value: number }[]
+  /** Figures, for a summary. */
+  stats?: { label: string, value: string }[]
+}
+
+/** What the scaffold draws for one user story. */
+export interface ScaffoldStoryPlan {
+  /** The story's code — always one of the codes the planner was given. */
+  code: string
+  /** The top-menu section, inside the story's own area, this story belongs to. */
+  section: string
+  /** The screen name the story's implementation should adopt: `{section}/{purpose}`. */
+  screen: string
+  /** The dashboard widget this story owns. */
+  widget: { kind: WidgetKind, title: string, description: string }
+  /** What the placeholder shows until the story is implemented. */
+  sketch: SketchContent
+  /** Whether this widget is important enough to also appear on its area's home screen. */
+  home: boolean
+  /**
+   * The story whose preview this one renders instead of drawing its own.
+   *
+   * A pure OPTIMIZATION hint, and every consumer treats it as untrusted: absent, dropped, or
+   * naming a code that is not in the plan, the story falls back to owning its own widget and the
+   * drawn tree is exactly what it is today. It exists because a main flow's consecutive steps act
+   * on the SAME record through the same shape, and drawing a near-duplicate form for each one
+   * fills an area with previews that differ only in their heading.
+   *
+   * The arrow points at the OWNER, and only ever backwards in plan order — `fillScaffoldPlan`
+   * resolves and clamps it, so nothing downstream has to reason about cycles or forward
+   * references.
+   */
+  sharesWidgetWith?: string
+  /**
+   * The story whose SCREEN this one renders instead of drawing its own.
+   *
+   * Same rules and the same clamp as {@link sharesWidgetWith}, and deliberately a separate field:
+   * two steps can want one form on one screen, or one form reached from two screens, and
+   * collapsing both decisions into one flag makes the second unexpressible.
+   */
+  sharesScreenWith?: string
+}
+
+/** One area's shape: how its top menu is divided, and how it introduces itself. */
+export interface ScaffoldAreaPlan {
+  area: ProjectArea
+  /** The introduction widget on the area's home screen. */
+  intro: { title: string, text: string }
+  /** The top-menu sections of this area, in menu order. */
+  sections: string[]
+}
+
+/**
+ * What the application calls itself, everywhere a machine reads it.
+ *
+ * Not branding and not decoration: this is what the document's `<title>`, its description and its
+ * icon are built from. The one page an anonymous visitor can reach is a sign-in page, served from
+ * a machine-generated hostname — and a sign-in page carrying no title, no description and no icon
+ * is the exact shape Safe Browsing scores as credential phishing. A generated application that
+ * never replaced the template's placeholder ships that shape by default, so the identity is
+ * planned here and stamped like every other part of the scaffold.
+ */
+export interface ProductIdentity {
+  /** The product's own name, as a person reads it. Never a slug, never a placeholder. */
+  name: string
+  /** One sentence saying what the product is, for `<meta name="description">`. */
+  description: string
+}
+
+/** The guest area's landing page — the product's public face. */
+export interface GuestHomePlan {
+  hero: { eyebrow: string, headline: string, sub: string, cta: string }
+  problem: { title: string, text: string }
+  solution: { title: string, text: string }
+  features: { title: string, text: string }[]
+  testimonials: { quote: string, name: string, role: string }[]
+}
+
+/**
+ * Everything one cheap call decides about a project's scaffolding.
+ *
+ * It is a PLAN, never code: the stamping that turns it into screens, widgets and dashboards is
+ * deterministic, so the same plan always produces the same tree and a re-scaffold is idempotent.
+ */
+export interface ScaffoldPlan {
+  /** What this application is called and what it says it is. */
+  identity: ProductIdentity
+  guestHome: GuestHomePlan
+  areas: ScaffoldAreaPlan[]
+  stories: ScaffoldStoryPlan[]
+  /**
+   * How this product's illustrations should look — geometry and motif, in the design system's
+   * own vocabulary. The one field here that is prose, because it is read by a model.
+   */
+  motifs: string
+}