@markii/pack 0.9.0 → 0.10.0

package/dist/components.d.ts

@@ -18,16 +18,64 @@ export type PackComponentKind = 'inline' | 'leaf' | 'container';
  * spelled differently in two places within this package and drift apart.
  */
 export declare const PACK_COMPONENT_KINDS: readonly PackComponentKind[];
+/**
+ * The charset a pack's declared attribute name must match: a leading
+ * lowercase letter, then lowercase letters, digits, and hyphens. Looser
+ * than `namespace.ts`'s `SEGMENT_RE` on purpose, because an attribute name
+ * is not a namespace: it never composes with another segment, so a
+ * trailing or doubled hyphen is ugly rather than ambiguous, and there is
+ * nothing for a stricter rule to protect.
+ *
+ * No prototype-member rejection here, unlike `validatePackName`: declared
+ * attributes travel as an ARRAY, never as an object keyed by attribute
+ * name, so an attribute called `constructor` is only ever compared as a
+ * string and can never reach a prototype chain.
+ */
+export declare const PACK_ATTRIBUTE_NAME_PATTERN: RegExp;
+/** Whether `name` is a usable pack attribute name. Never throws; a non-string is simply `false`. */
+export declare function isPackAttributeName(name: unknown): name is string;
+/**
+ * One attribute a pack component declares in `pack.json`, so a host's
+ * completion, hover, and insert skeleton can offer it the same way they
+ * offer a standard component's contract attributes. Every field but `name`
+ * is optional: a pack that declares only names still gets attribute-name
+ * completion.
+ *
+ * This is metadata, not enforcement. Nothing validates a rendered
+ * directive's attributes against it: the renderer stays registry-driven
+ * and a component owns how it reads its own props (Architecture rules 2
+ * and 5). A `required` attribute an author leaves out is the component's
+ * problem to handle, exactly as before.
+ */
+export interface PackComponentAttribute {
+    /** The name an author writes inside `{...}`, e.g. `from`. Matches `PACK_ATTRIBUTE_NAME_PATTERN`. */
+    readonly name: string;
+    /** Human-readable semantics, shown in a completion row and in hover documentation. */
+    readonly description?: string;
+    /** `true` when the component is incomplete without this attribute. A required attribute is pre-filled by the insert skeleton. */
+    readonly required?: boolean;
+    /** The closed set of allowed values, when the attribute is an enum. Non-empty when present; offered as attribute-value completions. */
+    readonly values?: readonly string[];
+    /** The value used when the attribute is absent. When `values` is present, this is one of them. */
+    readonly default?: string;
+}
 /**
  * The object form of a `components` manifest entry. `source` is the only
  * required field (a pack-relative path, same meaning as the string
- * shorthand); `description` and `kind` are optional metadata a host can
- * surface in an insert-component catalog or similar UI.
+ * shorthand); `description`, `kind`, and `attributes` are optional metadata
+ * a host can surface in an insert-component catalog, a completion popup, or
+ * hover documentation.
  */
 export interface PackComponentDefinition {
     source: string;
     description?: string;
     kind?: PackComponentKind;
+    /**
+     * The component's declared attributes, in the order a host should offer
+     * them. Optional, and omitted rather than empty when the manifest
+     * declared none: `attributes: []` normalizes to absent.
+     */
+    attributes?: readonly PackComponentAttribute[];
 }
 /**
  * A `components` manifest entry: either the original string shorthand
@@ -37,13 +85,14 @@ export interface PackComponentDefinition {
 export type PackComponentEntry = string | PackComponentDefinition;
 /**
  * One component's declared metadata with both entry forms normalized to
- * the same shape. `description`/`kind` are only present when the manifest
- * declared them (the string shorthand never has either).
+ * the same shape. `description`/`kind`/`attributes` are only present when
+ * the manifest declared them (the string shorthand never has any of them).
  */
 export interface ResolvedPackComponent {
     readonly source: string;
     readonly description?: string;
     readonly kind?: PackComponentKind;
+    readonly attributes?: readonly PackComponentAttribute[];
 }
 /** Same as `ResolvedPackComponent`, plus the local name it was declared under. */
 export interface PackComponentListing extends ResolvedPackComponent {

package/dist/components.js

@@ -11,6 +11,93 @@ export const PACK_COMPONENT_KINDS = [
     'container',
 ];
 const PACK_COMPONENT_KIND_SET = new Set(PACK_COMPONENT_KINDS);
+/**
+ * The charset a pack's declared attribute name must match: a leading
+ * lowercase letter, then lowercase letters, digits, and hyphens. Looser
+ * than `namespace.ts`'s `SEGMENT_RE` on purpose, because an attribute name
+ * is not a namespace: it never composes with another segment, so a
+ * trailing or doubled hyphen is ugly rather than ambiguous, and there is
+ * nothing for a stricter rule to protect.
+ *
+ * No prototype-member rejection here, unlike `validatePackName`: declared
+ * attributes travel as an ARRAY, never as an object keyed by attribute
+ * name, so an attribute called `constructor` is only ever compared as a
+ * string and can never reach a prototype chain.
+ */
+export const PACK_ATTRIBUTE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Whether `name` is a usable pack attribute name. Never throws; a non-string is simply `false`. */
+export function isPackAttributeName(name) {
+    return typeof name === 'string' && PACK_ATTRIBUTE_NAME_PATTERN.test(name);
+}
+/**
+ * Reads one own property off an already-narrowed object, or `undefined`
+ * when it is absent. `Object.hasOwn` only, matching this package's rule
+ * throughout: an inherited property is never read, so an object built with
+ * a hostile prototype cannot smuggle a value through the prototype chain.
+ */
+function ownProperty(entry, key) {
+    return Object.hasOwn(entry, key)
+        ? entry[key]
+        : undefined;
+}
+/**
+ * The lenient half of attribute handling, for `resolvePackComponent`: a
+ * malformed attribute entry is dropped rather than rejected, the same way
+ * a malformed `description` or `kind` is simply omitted here. The strict
+ * half lives in `./manifest.ts`, which rejects the whole manifest instead
+ * so a pack author sees their mistake at validation time rather than
+ * silently losing an attribute from a completion popup.
+ */
+function resolveAttribute(entry) {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        return undefined;
+    }
+    const name = ownProperty(entry, 'name');
+    if (!isPackAttributeName(name))
+        return undefined;
+    const result = { name };
+    const description = ownProperty(entry, 'description');
+    if (typeof description === 'string' && description.length > 0) {
+        result.description = description;
+    }
+    if (ownProperty(entry, 'required') === true) {
+        result.required = true;
+    }
+    const values = ownProperty(entry, 'values');
+    if (Array.isArray(values)) {
+        const cleaned = values.filter((value) => typeof value === 'string' && value.length > 0);
+        if (cleaned.length > 0)
+            result.values = cleaned;
+    }
+    const defaultValue = ownProperty(entry, 'default');
+    if (typeof defaultValue === 'string' &&
+        defaultValue.length > 0 &&
+        (result.values === undefined || result.values.includes(defaultValue))) {
+        result.default = defaultValue;
+    }
+    return result;
+}
+/**
+ * Normalizes a declared `attributes` list: keeps declaration order, drops
+ * an entry `resolveAttribute` cannot make sense of, drops a duplicate name
+ * after the first, and returns `undefined` (rather than `[]`) when nothing
+ * survives, so "declared no attributes" and "declared an empty list" are
+ * the same state everywhere downstream.
+ */
+function resolveAttributes(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const seen = new Set();
+    const resolved = [];
+    for (const entry of raw) {
+        const attribute = resolveAttribute(entry);
+        if (attribute === undefined || seen.has(attribute.name))
+            continue;
+        seen.add(attribute.name);
+        resolved.push(attribute);
+    }
+    return resolved.length > 0 ? resolved : undefined;
+}
 /**
  * Normalizes a single `components` entry, string or object form, into the
  * common `ResolvedPackComponent` shape. This is THE accessor for reading
@@ -33,30 +120,25 @@ export function resolvePackComponent(entry) {
     if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
         return undefined;
     }
-    // Object.hasOwn only, matching this package's rule throughout: never read
-    // an inherited property, so an object built with a hostile prototype
-    // cannot smuggle a `source` through the prototype chain.
-    const source = Object.hasOwn(entry, 'source')
-        ? entry.source
-        : undefined;
+    const source = ownProperty(entry, 'source');
     if (typeof source !== 'string' || source.length === 0) {
         return undefined;
     }
     const result = {
         source,
     };
-    const description = Object.hasOwn(entry, 'description')
-        ? entry.description
-        : undefined;
+    const description = ownProperty(entry, 'description');
     if (typeof description === 'string' && description.length > 0) {
         result.description = description;
     }
-    const kind = Object.hasOwn(entry, 'kind')
-        ? entry.kind
-        : undefined;
+    const kind = ownProperty(entry, 'kind');
     if (typeof kind === 'string' && PACK_COMPONENT_KIND_SET.has(kind)) {
         result.kind = kind;
     }
+    const attributes = resolveAttributes(ownProperty(entry, 'attributes'));
+    if (attributes !== undefined) {
+        result.attributes = attributes;
+    }
     return result;
 }
 /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { PackManifest, PackManifestParseResult } from './manifest.js';
 export { parsePackManifest } from './manifest.js';
-export type { PackComponentDefinition, PackComponentEntry, PackComponentKind, PackComponentListing, ResolvedPackComponent, } from './components.js';
-export { PACK_COMPONENT_KINDS, packComponents, resolvePackComponent, } from './components.js';
+export type { PackComponentAttribute, PackComponentDefinition, PackComponentEntry, PackComponentKind, PackComponentListing, ResolvedPackComponent, } from './components.js';
+export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
 export type { ComposeDirectiveNameResult, NamespaceCollision, NamespaceValidationResult, } from './namespace.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export type { UsesResolution } from './uses.js';

package/dist/index.js

@@ -3,6 +3,6 @@
 // hand-rolled validation only. No registry loading, no `uses:` surfacing,
 // no sandboxed `require`, no filesystem reads: those are later slices.
 export { parsePackManifest } from './manifest.js';
-export { PACK_COMPONENT_KINDS, packComponents, resolvePackComponent, } from './components.js';
+export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/manifest.d.ts

@@ -11,8 +11,8 @@ import type { PackComponentEntry } from './components.js';
  * not maintain a closed enum of known engines. `components` maps a local
  * component name to either a pack-relative source path (the string
  * shorthand) or an object carrying that source plus optional `description`/
- * `kind` metadata (see `./components.ts`, `resolvePackComponent`,
- * `packComponents`).
+ * `kind`/`attributes` metadata (see `./components.ts`,
+ * `resolvePackComponent`, `packComponents`).
  *
  * Shared Lua modules are NOT a manifest field. docs/packs.md says they
  * travel under a conventional `scripts/` directory inside the pack
@@ -28,7 +28,8 @@ export interface PackManifest {
     engine: string;
     /**
      * Local component name -> a pack-relative source path, or an object
-     * naming that source plus optional `description`/`kind` metadata. Read
+     * naming that source plus optional `description`/`kind`/`attributes`
+     * metadata. Read
      * this map only through `resolvePackComponent`/`packComponents`
      * (`./components.ts`) rather than inspecting entries directly — that is
      * the one place both forms are normalized.

package/dist/manifest.js

@@ -1,10 +1,25 @@
 import { validateLocalComponentName, validatePackName } from './namespace.js';
-import { PACK_COMPONENT_KINDS } from './components.js';
+import { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, } from './components.js';
 const KNOWN_TOP_LEVEL_KEYS = new Set(['name', 'engine', 'components']);
 // The keys a component's object-form entry may carry, and which of those
 // are required. Mirrors KNOWN_TOP_LEVEL_KEYS's role for the manifest root:
 // an unrecognized key here is a forward-compatible warning, not an error.
-const KNOWN_COMPONENT_KEYS = new Set(['source', 'description', 'kind']);
+const KNOWN_COMPONENT_KEYS = new Set([
+    'source',
+    'description',
+    'kind',
+    'attributes',
+]);
+// The keys one entry of a component's `attributes` array may carry. Same
+// posture as KNOWN_COMPONENT_KEYS one level up: an unrecognized key is a
+// forward-compatible warning, everything recognized is validated strictly.
+const KNOWN_ATTRIBUTE_KEYS = new Set([
+    'name',
+    'description',
+    'required',
+    'values',
+    'default',
+]);
 // Checked against ./components.ts's single runtime list rather than a second
 // copy of the three values, so the validator and the accessor can never
 // disagree about what a valid `kind` is.
@@ -12,6 +27,118 @@ const PACK_COMPONENT_KIND_SET = new Set(PACK_COMPONENT_KINDS);
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/**
+ * The strict half of attribute validation (the lenient half lives in
+ * `./components.ts`'s `resolveAttribute`, which a consumer may call on
+ * never-validated JSON). Anything malformed here pushes an error and
+ * rejects the WHOLE manifest, so a pack author is told what is wrong at
+ * validation time rather than quietly losing an attribute from a
+ * completion popup later.
+ *
+ * Returns the sanitized list, or `undefined` when anything failed. An
+ * empty declared list is valid and returns `[]`; the caller drops that
+ * rather than storing it, so "declared nothing" and "declared an empty
+ * list" are one state downstream.
+ */
+function parseComponentAttributes(componentKey, raw, errors, warnings) {
+    const parsed = [];
+    const seen = new Set();
+    let valid = true;
+    for (const [index, entry] of raw.entries()) {
+        const where = `"components.${componentKey}.attributes[${String(index)}]"`;
+        if (!isPlainObject(entry)) {
+            errors.push(`${where} must be an object with a "name" field`);
+            valid = false;
+            continue;
+        }
+        const rawName = Object.hasOwn(entry, 'name') ? entry.name : undefined;
+        if (!isPackAttributeName(rawName)) {
+            errors.push(`${where}.name must be a non-empty string matching ${PACK_ATTRIBUTE_NAME_PATTERN.source}`);
+            valid = false;
+            continue;
+        }
+        if (seen.has(rawName)) {
+            errors.push(`${where}.name "${rawName}" is declared more than once`);
+            valid = false;
+            continue;
+        }
+        seen.add(rawName);
+        let entryValid = true;
+        let description;
+        if (Object.hasOwn(entry, 'description')) {
+            const rawDescription = entry.description;
+            if (typeof rawDescription !== 'string' || rawDescription.length === 0) {
+                errors.push(`${where}.description must be a non-empty string`);
+                entryValid = false;
+            }
+            else {
+                description = rawDescription;
+            }
+        }
+        let required;
+        if (Object.hasOwn(entry, 'required')) {
+            const rawRequired = entry.required;
+            if (typeof rawRequired !== 'boolean') {
+                errors.push(`${where}.required must be a boolean`);
+                entryValid = false;
+            }
+            else {
+                required = rawRequired;
+            }
+        }
+        let values;
+        if (Object.hasOwn(entry, 'values')) {
+            const rawValues = entry.values;
+            if (!Array.isArray(rawValues) ||
+                rawValues.length === 0 ||
+                rawValues.some((value) => typeof value !== 'string' || value.length === 0)) {
+                errors.push(`${where}.values must be a non-empty array of non-empty strings`);
+                entryValid = false;
+            }
+            else {
+                values = rawValues;
+            }
+        }
+        let defaultValue;
+        if (Object.hasOwn(entry, 'default')) {
+            const rawDefault = entry.default;
+            if (typeof rawDefault !== 'string' || rawDefault.length === 0) {
+                errors.push(`${where}.default must be a non-empty string`);
+                entryValid = false;
+            }
+            else if (values !== undefined && !values.includes(rawDefault)) {
+                errors.push(`${where}.default "${rawDefault}" must be one of its "values": ${values.join(', ')}`);
+                entryValid = false;
+            }
+            else {
+                defaultValue = rawDefault;
+            }
+        }
+        for (const attributeKey of Object.keys(entry)) {
+            if (Object.hasOwn(entry, attributeKey) &&
+                !KNOWN_ATTRIBUTE_KEYS.has(attributeKey)) {
+                warnings.push(`unknown pack component attribute key ${where}.${attributeKey} (ignored by this implementation)`);
+            }
+        }
+        if (!entryValid) {
+            valid = false;
+            continue;
+        }
+        // Rebuilt rather than stored raw, the same discipline the component
+        // object form uses: only checked fields ever reach the result.
+        const sanitized = { name: rawName };
+        if (description !== undefined)
+            sanitized.description = description;
+        if (required !== undefined)
+            sanitized.required = required;
+        if (values !== undefined)
+            sanitized.values = values;
+        if (defaultValue !== undefined)
+            sanitized.default = defaultValue;
+        parsed.push(sanitized);
+    }
+    return valid ? parsed : undefined;
+}
 /**
  * Hand-rolled `pack.json` validation (no schema library — see AGENTS.md
  * dependency policy), mirroring `@markii/bundle`'s `parseManifest` style:
@@ -73,9 +200,10 @@ export function parsePackManifest(json) {
     // --- components (required) ---
     //
     // Each entry is either the string shorthand (a pack-relative source path)
-    // or an object form { source, description?, kind? }. A malformed entry —
-    // wrong value type, invalid key, bad `kind`, non-string `description`,
-    // missing/empty `source` in object form — pushes an error and rejects the
+    // or an object form { source, description?, kind?, attributes? }. A
+    // malformed entry — wrong value type, invalid key, bad `kind`, non-string
+    // `description`, a malformed `attributes` list, missing/empty `source` in
+    // object form — pushes an error and rejects the
     // WHOLE manifest, matching this file's existing posture for a bad
     // top-level field. An unrecognized key INSIDE a component object is a
     // forward-compatible warning, the same posture KNOWN_TOP_LEVEL_KEYS uses
@@ -156,6 +284,23 @@ export function parsePackManifest(json) {
                     kind = rawKind;
                 }
             }
+            let attributes;
+            if (Object.hasOwn(value, 'attributes')) {
+                const rawAttributes = value.attributes;
+                if (!Array.isArray(rawAttributes)) {
+                    errors.push(`"components.${key}.attributes" must be an array of attribute objects`);
+                    entryValid = false;
+                }
+                else {
+                    const parsed = parseComponentAttributes(key, rawAttributes, errors, warnings);
+                    if (parsed === undefined) {
+                        entryValid = false;
+                    }
+                    else if (parsed.length > 0) {
+                        attributes = parsed;
+                    }
+                }
+            }
             for (const componentKey of Object.keys(value)) {
                 if (Object.hasOwn(value, componentKey) &&
                     !KNOWN_COMPONENT_KEYS.has(componentKey)) {
@@ -175,6 +320,8 @@ export function parsePackManifest(json) {
                 sanitized.description = description;
             if (kind !== undefined)
                 sanitized.kind = kind;
+            if (attributes !== undefined)
+                sanitized.attributes = attributes;
             result[key] = sanitized;
         }
         if (Object.keys(componentsObj).length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/pack",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Component pack contract for Markii (docs/packs.md): the pack.json manifest shape, namespace and engine rules, and hand-rolled validation. No React, no parsing, no bundle loading.",
   "keywords": [
     "markdown",