@smallpen/core 0.1.0-alpha.1

package/src/projection-values.mjs

@@ -0,0 +1,138 @@
+import { resolveContext } from "./contexts.mjs";
+import { resolveEffectiveToken } from "./effective-tokens.mjs";
+import { fail } from "./errors.mjs";
+
+const FIELD_TYPES = new Map([
+  ["backgroundBlur", ["other", "number"]],
+  ["blur", ["other", "number"]],
+  ["cornerRadius", ["border-radius", "dimension", "dimensions", "number"]],
+  ["fill", ["color"]],
+  ["fontFamily", ["font-family", "string"]],
+  ["fontSize", ["dimension", "dimensions", "font-size", "number"]],
+  ["fontWeight", ["font-weight", "number"]],
+  ["height", ["dimension", "dimensions", "number", "sizing"]],
+  ["itemSpacing", ["dimension", "dimensions", "number", "spacing"]],
+  ["opacity", ["number", "opacity"]],
+  ["paddingBottom", ["dimension", "dimensions", "number", "spacing"]],
+  ["paddingLeft", ["dimension", "dimensions", "number", "spacing"]],
+  ["paddingRight", ["dimension", "dimensions", "number", "spacing"]],
+  ["paddingTop", ["dimension", "dimensions", "number", "spacing"]],
+  ["shadow", ["shadow"]],
+  ["strokeWidth", ["stroke-width", "dimension", "dimensions", "number"]],
+  ["typography", ["typography"]],
+  ["width", ["dimension", "dimensions", "number", "sizing"]],
+]);
+
+function compatible(field, token) {
+  const baseField = field.startsWith("fills.") ? "fill" : field;
+  return FIELD_TYPES.get(baseField)?.includes(token.type) === true;
+}
+
+function assign(node, field, value) {
+  if (field === "fill") {
+    node.fills = [{ color: value, type: "solid" }];
+    return;
+  }
+  if (field === "strokeWidth") {
+    if (!Array.isArray(node.strokes) || node.strokes.length === 0) {
+      fail(
+        "missing_token_binding_target",
+        `Token binding target is missing: ${field}`,
+        { field, nodeId: node.id },
+      );
+    }
+    node.strokes = node.strokes.map((stroke) => ({
+      ...stroke,
+      width: value,
+    }));
+    return;
+  }
+  const fillMatch = /^fills\.(\d+)$/.exec(field);
+  if (fillMatch) {
+    const index = Number(fillMatch[1]);
+    const fills = structuredClone(node.fills ?? []);
+    if (!fills[index]) {
+      fail("missing_token_binding_target", `Token binding target is missing: ${field}`, {
+        field,
+        nodeId: node.id,
+      });
+    }
+    fills[index] = { ...fills[index], color: value, type: "solid" };
+    node.fills = fills;
+    return;
+  }
+  if (field === "typography") {
+    node.textStyle = { ...(node.textStyle ?? {}), ...structuredClone(value) };
+    return;
+  }
+  if (["fontFamily", "fontSize", "fontWeight"].includes(field)) {
+    node.textStyle = { ...(node.textStyle ?? {}), [field]: value };
+    return;
+  }
+  node[field] = structuredClone(value);
+}
+
+export function applyEffectiveTokenBindings(nodeValue, product, options = {}) {
+  const node = structuredClone(nodeValue);
+  for (const [field, reference] of Object.entries(node.tokenBindings ?? {})) {
+    const effective = resolveEffectiveToken(product, reference, options);
+    if (!effective) {
+      fail("missing_token", `Token not found: ${reference.assetId}`, {
+        field,
+        nodeId: node.id,
+        path: `${node.id}.tokenBindings.${field}`,
+        reference,
+      });
+    }
+    if (!compatible(field, effective.token)) {
+      fail(
+        "binding_type_mismatch",
+        `Token type ${effective.token.type} cannot bind to ${field}`,
+        {
+          field,
+          nodeId: node.id,
+          path: `${node.id}.tokenBindings.${field}`,
+          tokenId: effective.token.id,
+          tokenType: effective.token.type,
+        },
+      );
+    }
+    assign(node, field, effective.value);
+  }
+  return node;
+}
+
+export function projectEffectiveSnapshot(product, options = {}) {
+  const foundation = options.foundation;
+  const libraries = options.libraries ?? [];
+  const context = resolveContext(product, foundation, options.context ?? {});
+  const entries = structuredClone(product.entries);
+  for (const entry of product.manifest.entries.screens) {
+    for (const presentation of entries[entry].presentations) {
+      for (const [nodeId, node] of Object.entries(presentation.nodes)) {
+        presentation.nodes[nodeId] = applyEffectiveTokenBindings(node, product, {
+          context,
+          foundation,
+          libraries,
+        });
+      }
+    }
+  }
+  for (const entry of product.manifest.entries.components) {
+    for (const set of entries[entry].componentSets ?? []) {
+      for (const variant of set.variants ?? []) {
+        for (const [nodeId, node] of Object.entries(variant.nodes)) {
+          variant.nodes[nodeId] = applyEffectiveTokenBindings(node, product, {
+            context, foundation, libraries,
+          });
+        }
+      }
+    }
+  }
+  return {
+    ...product,
+    domain: product.domain,
+    entries,
+    projection: { context },
+  };
+}

package/src/requirements-domain.mjs

@@ -0,0 +1,222 @@
+import { fail } from "./errors.mjs";
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function stableId(value, prefix, code, path) {
+  if (
+    typeof value !== "string" ||
+    !value.startsWith(prefix) ||
+    !/^[a-zA-Z0-9_-]+$/.test(value)
+  ) {
+    fail(code, `${path} must begin with ${prefix}`, { path, value });
+  }
+  return value;
+}
+
+function nonEmpty(value, code, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    fail(code, `${path} must be a non-empty string`, { path, value });
+  }
+  return value;
+}
+
+function assetReference(value, prefix, path) {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).length !== 2 ||
+    typeof value.packageId !== "string" ||
+    !value.packageId.startsWith("pkg_") ||
+    typeof value.assetId !== "string" ||
+    !value.assetId.startsWith(prefix)
+  ) {
+    fail("invalid_asset_reference", `${path} is invalid`, { path });
+  }
+  return structuredClone(value);
+}
+
+export function parseDesignTarget(value, path) {
+  if (!isRecord(value) || typeof value.kind !== "string") {
+    fail("invalid_design_target", `${path} is invalid`, { path });
+  }
+  if (value.kind === "node") {
+    if (
+      Object.keys(value).length !== 4 ||
+      typeof value.presentationId !== "string" ||
+      !value.presentationId.startsWith("pres_") ||
+      typeof value.nodeId !== "string" ||
+      !value.nodeId.startsWith("node_")
+    ) {
+      fail("invalid_design_target", `${path} Node target is invalid`);
+    }
+    return {
+      kind: "node",
+      nodeId: value.nodeId,
+      presentationId: value.presentationId,
+      screen: assetReference(value.screen, "scr_", `${path}.screen`),
+    };
+  }
+  if (value.kind === "screen") {
+    if (Object.keys(value).length !== 2) {
+      fail("invalid_design_target", `${path} Screen target is invalid`);
+    }
+    return {
+      kind: "screen",
+      screen: assetReference(value.screen, "scr_", `${path}.screen`),
+    };
+  }
+  const idFields = {
+    flow: ["flowId", "flow_"],
+    interaction: ["interactionId", "int_"],
+    scenario: ["scenarioId", "scn_"],
+  };
+  const descriptor = idFields[value.kind];
+  if (!descriptor || Object.keys(value).length !== 2) {
+    fail("invalid_design_target", `${path}.kind is unsupported`, {
+      kind: value.kind,
+      path,
+    });
+  }
+  const [field, prefix] = descriptor;
+  stableId(value[field], prefix, "invalid_design_target", `${path}.${field}`);
+  return structuredClone(value);
+}
+
+function parseRequirement(value, path) {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).length !== 4 ||
+    !Array.isArray(value.links) ||
+    typeof value.markdown !== "string"
+  ) {
+    fail("invalid_requirement", `${path} is invalid`);
+  }
+  stableId(value.id, "req_", "invalid_requirement_id", `${path}.id`);
+  nonEmpty(value.title, "invalid_requirement_title", `${path}.title`);
+  return {
+    id: value.id,
+    links: value.links.map((link, index) =>
+      parseDesignTarget(link, `${path}.links[${index}]`),
+    ),
+    markdown: value.markdown,
+    title: value.title,
+  };
+}
+
+function parseFlow(value, path) {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).length !== 3 ||
+    !Array.isArray(value.interactionIds) ||
+    value.interactionIds.some(
+      (id) => typeof id !== "string" || !id.startsWith("int_"),
+    ) ||
+    new Set(value.interactionIds).size !== value.interactionIds.length
+  ) {
+    fail("invalid_flow", `${path} is invalid`);
+  }
+  stableId(value.id, "flow_", "invalid_flow_id", `${path}.id`);
+  nonEmpty(value.name, "invalid_flow_name", `${path}.name`);
+  return {
+    id: value.id,
+    interactionIds: [...value.interactionIds],
+    name: value.name,
+  };
+}
+
+function parseAnnotation(value, path) {
+  if (!isRecord(value) || !Array.isArray(value.tags)) {
+    fail("invalid_semantic_annotation", `${path} is invalid`);
+  }
+  const fields = new Set(["description", "id", "role", "tags", "target"]);
+  if (Object.keys(value).some((field) => !fields.has(field))) {
+    fail("invalid_semantic_annotation", `${path} fields are invalid`);
+  }
+  stableId(value.id, "ann_", "invalid_annotation_id", `${path}.id`);
+  if (
+    value.description !== undefined &&
+    typeof value.description !== "string"
+  ) {
+    fail(
+      "invalid_annotation_description",
+      `${path}.description must be a string`,
+    );
+  }
+  if (
+    value.role !== undefined &&
+    (typeof value.role !== "string" || value.role.length === 0)
+  ) {
+    fail("invalid_annotation_role", `${path}.role must be non-empty`);
+  }
+  if (
+    value.tags.some((tag) => typeof tag !== "string" || tag.length === 0) ||
+    new Set(value.tags).size !== value.tags.length
+  ) {
+    fail("invalid_annotation_tags", `${path}.tags must contain unique strings`);
+  }
+  return {
+    ...(value.description === undefined
+      ? {}
+      : { description: value.description }),
+    id: value.id,
+    ...(value.role === undefined ? {} : { role: value.role }),
+    tags: [...value.tags],
+    target: parseDesignTarget(value.target, `${path}.target`),
+  };
+}
+
+export function parseRequirementEntries(manifest, entries) {
+  const annotations = new Map();
+  const flows = new Map();
+  const requirements = new Map();
+  for (const entry of manifest.entries.requirements) {
+    const value = entries[entry];
+    if (
+      !isRecord(value) ||
+      Object.keys(value).length !== 3 ||
+      !Array.isArray(value.annotations) ||
+      !Array.isArray(value.flows) ||
+      !Array.isArray(value.requirements)
+    ) {
+      fail(
+        "invalid_requirement_file",
+        `${entry} requires annotations, flows, and requirements arrays`,
+      );
+    }
+    for (const [index, candidate] of value.annotations.entries()) {
+      const annotation = parseAnnotation(
+        candidate,
+        `${entry}.annotations[${index}]`,
+      );
+      if (annotations.has(annotation.id)) {
+        fail(
+          "duplicate_annotation_id",
+          `Duplicate Annotation id: ${annotation.id}`,
+        );
+      }
+      annotations.set(annotation.id, annotation);
+    }
+    for (const [index, candidate] of value.flows.entries()) {
+      const flow = parseFlow(candidate, `${entry}.flows[${index}]`);
+      if (flows.has(flow.id)) {
+        fail("duplicate_flow_id", `Duplicate Flow id: ${flow.id}`);
+      }
+      flows.set(flow.id, flow);
+    }
+    for (const [index, candidate] of value.requirements.entries()) {
+      const requirement = parseRequirement(
+        candidate,
+        `${entry}.requirements[${index}]`,
+      );
+      if (requirements.has(requirement.id)) {
+        fail(
+          "duplicate_requirement_id",
+          `Duplicate Requirement id: ${requirement.id}`,
+        );
+      }
+      requirements.set(requirement.id, requirement);
+    }
+  }
+  return { annotations, flows, requirements };
+}

package/src/scenarios-domain.mjs

@@ -0,0 +1,268 @@
+import { fail } from "./errors.mjs";
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function stableId(value, prefix, code, path) {
+  if (
+    typeof value !== "string" ||
+    !value.startsWith(prefix) ||
+    !/^[a-zA-Z0-9_-]+$/.test(value)
+  ) {
+    fail(code, `${path} must begin with ${prefix}`, { path, value });
+  }
+  return value;
+}
+
+function nonEmpty(value, code, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    fail(code, `${path} must be a non-empty string`, { path, value });
+  }
+  return value;
+}
+
+function stringRecord(value, code, path) {
+  if (!isRecord(value)) fail(code, `${path} must contain an object`, { path });
+  for (const [field, child] of Object.entries(value)) {
+    if (field.length === 0 || typeof child !== "string" || child.length === 0) {
+      fail(code, `${path} must map strings to strings`, { path });
+    }
+  }
+  return structuredClone(value);
+}
+
+function assetReference(value, prefix, path) {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).length !== 2 ||
+    typeof value.packageId !== "string" ||
+    !value.packageId.startsWith("pkg_") ||
+    typeof value.assetId !== "string" ||
+    !value.assetId.startsWith(prefix)
+  ) {
+    fail("invalid_asset_reference", `${path} is invalid`, { path });
+  }
+  return structuredClone(value);
+}
+
+function parseTarget(value, path) {
+  if (!isRecord(value)) fail("invalid_scenario_target", `${path} is invalid`);
+  if (value.kind === "screen") {
+    if (
+      Object.keys(value).length !== 3 ||
+      typeof value.presentationId !== "string" ||
+      !value.presentationId.startsWith("pres_")
+    ) {
+      fail("invalid_screen_reference", `${path} Screen target is invalid`);
+    }
+    return {
+      kind: "screen",
+      presentationId: value.presentationId,
+      screen: assetReference(value.screen, "scr_", `${path}.screen`),
+    };
+  }
+  if (value.kind === "component") {
+    if (Object.keys(value).length !== 3) {
+      fail("invalid_component_target", `${path} Component target is invalid`);
+    }
+    return {
+      component: assetReference(
+        value.component,
+        "cmp_",
+        `${path}.component`,
+      ),
+      kind: "component",
+      variant: stringRecord(
+        value.variant,
+        "invalid_component_variant_selection",
+        `${path}.variant`,
+      ),
+    };
+  }
+  fail(
+    "invalid_scenario_target_kind",
+    `${path}.kind must be screen or component`,
+  );
+}
+
+function parseOverrideValue(value, path) {
+  if (
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  ) {
+    return value;
+  }
+  if (
+    Array.isArray(value) &&
+    value.every(
+      (paint) =>
+        isRecord(paint) &&
+        paint.type === "solid" &&
+        typeof paint.color === "string" &&
+        (paint.opacity === undefined ||
+          (typeof paint.opacity === "number" &&
+            Number.isFinite(paint.opacity) &&
+            paint.opacity >= 0 &&
+            paint.opacity <= 1)),
+    )
+  ) {
+    return structuredClone(value);
+  }
+  fail("invalid_scenario_override", `${path} is unsupported`, { path });
+}
+
+function parseAction(value, path) {
+  if (!isRecord(value) || typeof value.type !== "string") {
+    fail("invalid_scenario_action", `${path} must contain an object`);
+  }
+  if (
+    value.type === "set-state" &&
+    Object.keys(value).length === 3 &&
+    typeof value.axisId === "string" &&
+    value.axisId.startsWith("axis_") &&
+    typeof value.value === "string" &&
+    value.value.length > 0
+  ) {
+    return structuredClone(value);
+  }
+  if (
+    value.type === "set-text" &&
+    Object.keys(value).length === 3 &&
+    typeof value.nodeId === "string" &&
+    value.nodeId.startsWith("node_") &&
+    typeof value.value === "string"
+  ) {
+    return structuredClone(value);
+  }
+  if (
+    value.type === "set-visibility" &&
+    Object.keys(value).length === 3 &&
+    typeof value.nodeId === "string" &&
+    value.nodeId.startsWith("node_") &&
+    typeof value.visible === "boolean"
+  ) {
+    return structuredClone(value);
+  }
+  if (
+    value.type === "set-override" &&
+    Object.keys(value).length === 3 &&
+    typeof value.overridePath === "string" &&
+    value.overridePath.length > 0
+  ) {
+    return {
+      overridePath: value.overridePath,
+      type: "set-override",
+      value: parseOverrideValue(value.value, `${path}.value`),
+    };
+  }
+  fail(
+    "unsupported_scenario_action",
+    `${path} must use a finite declarative Scenario action`,
+    { path, type: value.type },
+  );
+}
+
+function parseScenario(value, path) {
+  if (!isRecord(value)) fail("invalid_scenario", `${path} is invalid`);
+  const fields = new Set([
+    "actions",
+    "context",
+    "expectedVisibleNodeIds",
+    "fixture",
+    "id",
+    "name",
+    "target",
+    "viewport",
+  ]);
+  if (
+    Object.keys(value).length !== fields.size ||
+    Object.keys(value).some((field) => !fields.has(field))
+  ) {
+    fail("invalid_scenario", `${path} fields are invalid`);
+  }
+  stableId(value.id, "scn_", "invalid_scenario_id", `${path}.id`);
+  nonEmpty(value.name, "invalid_scenario_name", `${path}.name`);
+  if (!Array.isArray(value.actions)) {
+    fail("invalid_scenario_actions", `${path}.actions must be an array`);
+  }
+  if (
+    !Array.isArray(value.expectedVisibleNodeIds) ||
+    value.expectedVisibleNodeIds.some(
+      (nodeId) => typeof nodeId !== "string" || !nodeId.startsWith("node_"),
+    ) ||
+    new Set(value.expectedVisibleNodeIds).size !==
+      value.expectedVisibleNodeIds.length
+  ) {
+    fail(
+      "invalid_visibility_expectation",
+      `${path}.expectedVisibleNodeIds must contain unique Node ids`,
+    );
+  }
+  if (
+    !isRecord(value.fixture) ||
+    Object.values(value.fixture).some(
+      (entry) =>
+        entry !== null &&
+        typeof entry !== "boolean" &&
+        typeof entry !== "string" &&
+        (typeof entry !== "number" || !Number.isFinite(entry)),
+    )
+  ) {
+    fail("invalid_fixture", `${path}.fixture must contain scalar values`);
+  }
+  if (
+    !isRecord(value.viewport) ||
+    !["height", "scale", "width"].every(
+      (field) =>
+        typeof value.viewport[field] === "number" &&
+        Number.isFinite(value.viewport[field]) &&
+        value.viewport[field] > 0,
+    ) ||
+    Object.keys(value.viewport).length !== 3
+  ) {
+    fail("invalid_viewport", `${path}.viewport values must be positive`);
+  }
+  return {
+    actions: value.actions.map((action, index) =>
+      parseAction(action, `${path}.actions[${index}]`),
+    ),
+    context: stringRecord(
+      value.context,
+      "invalid_scenario_context",
+      `${path}.context`,
+    ),
+    expectedVisibleNodeIds: [...value.expectedVisibleNodeIds],
+    fixture: structuredClone(value.fixture),
+    id: value.id,
+    name: value.name,
+    target: parseTarget(value.target, `${path}.target`),
+    viewport: structuredClone(value.viewport),
+  };
+}
+
+export function parseScenarioEntries(manifest, entries) {
+  const scenarios = new Map();
+  for (const entry of manifest.entries.scenarios) {
+    const value = entries[entry];
+    if (
+      !isRecord(value) ||
+      Object.keys(value).length !== 1 ||
+      !Array.isArray(value.scenarios)
+    ) {
+      fail(
+        "invalid_scenario_file",
+        `${entry} must contain a scenarios array`,
+      );
+    }
+    for (const [index, candidate] of value.scenarios.entries()) {
+      const scenario = parseScenario(candidate, `${entry}.scenarios[${index}]`);
+      if (scenarios.has(scenario.id)) {
+        fail("duplicate_scenario_id", `Duplicate Scenario id: ${scenario.id}`);
+      }
+      scenarios.set(scenario.id, scenario);
+    }
+  }
+  return scenarios;
+}