gbs-add-block 2.0.4 → 2.3.0

package/schema/passport-v1.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gramprokit.dev/schema/passport/1.json",
+  "title": "GramproKit Component Passport v1",
+  "description": "Machine-readable contract for one component. Generated from TypeScript source and merged with authored semantics. Published so external tooling can validate without depending on the generator.",
+  "type": "object",
+  "required": ["passportVersion", "identity", "source", "props", "events", "slots", "states", "coverage"],
+  "additionalProperties": false,
+  "properties": {
+    "passportVersion": { "const": "1.0.0" },
+
+    "identity": {
+      "type": "object",
+      "required": ["component", "folder", "exports"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "description": "Primary exported component name." },
+        "folder": { "type": "string", "description": "Install folder under component-lib/." },
+        "exports": { "type": "array", "items": { "type": "string" } },
+        "since": { "type": "string" }
+      }
+    },
+
+    "source": {
+      "type": "object",
+      "required": ["libraryVersion", "files", "sourceHash"],
+      "additionalProperties": false,
+      "description": "Provenance. sourceHash covers file contents only — no timestamps — so regeneration is byte-stable and CI comparison is meaningful.",
+      "properties": {
+        "libraryVersion": { "type": "string" },
+        "files": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "sourceHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+
+    "purpose": { "type": "string", "description": "Authored. What the component is for." },
+
+    "props": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "required", "origin"],
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "enum": ["string", "number", "boolean", "enum", "function", "other"] },
+          "values": { "type": "array", "items": { "type": "string" }, "description": "Present when type is enum." },
+          "signature": { "type": "string", "description": "Present when type is function." },
+          "typeText": { "type": "string", "description": "The TypeScript type as written." },
+          "required": { "type": "boolean" },
+          "default": { "description": "Derived from the component's destructuring default, when present." },
+          "origin": {
+            "enum": ["derived", "inherited", "manual", "local"],
+            "description": "derived = this project's source; inherited = a library type (React DOM) confirmed by the TypeChecker; manual/local = added by an overlay."
+          },
+          "description": { "type": "string" },
+          "descriptionOrigin": { "enum": ["jsdoc", "readme", "manual", "local"] },
+          "note": { "type": "string", "description": "Authored annotation from propNotes." },
+          "deprecated": { "type": ["boolean", "string"] }
+        },
+        "allOf": [
+          { "if": { "properties": { "type": { "const": "enum" } }, "required": ["type"] },
+            "then": { "required": ["values"] } },
+          { "if": { "required": ["description"] },
+            "then": { "required": ["descriptionOrigin"] } }
+        ]
+      }
+    },
+
+    "inherits": {
+      "type": "array",
+      "description": "External (library) base types. Deliberately NOT flattened: resolving ButtonHTMLAttributes yields hundreds of DOM props and buries the real API. A policy allowlist surfaces the useful ones inline with origin=inherited.",
+      "items": {
+        "type": "object",
+        "required": ["from"],
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "string" },
+          "omitted": { "type": "array", "items": { "type": "string" } },
+          "passthrough": { "type": "boolean" }
+        }
+      }
+    },
+
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "signature": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+
+    "slots": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "classNames slot keys, in declaration order."
+    },
+
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["attr"],
+        "additionalProperties": false,
+        "properties": {
+          "attr": { "type": "string", "pattern": "^data-" },
+          "values": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+
+    "accessibility": {
+      "type": "object",
+      "description": "Authored. What the component supplies versus what the consumer must still provide.",
+      "additionalProperties": false,
+      "properties": {
+        "supplied": { "type": "array", "items": { "type": "string" } },
+        "required": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "composition": {
+      "type": "object",
+      "description": "Authored. Structural rules a generator or agent must respect.",
+      "properties": {
+        "requiresAncestor": { "type": ["string", "null"] },
+        "allowedChildren": { "type": "array", "items": { "type": "string" } },
+        "mustNotContain": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "string" }
+      }
+    },
+
+    "operations": {
+      "type": "object",
+      "description": "Authoritative, validator-compatible. Only declared where the component genuinely exposes a deterministic operation surface. An operation is never claimed because an AI use case sounds plausible.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["summary", "apiMethod"],
+        "properties": {
+          "summary": { "type": "string" },
+          "apiMethod": { "type": "string", "description": "Method on the component's imperative API." },
+          "input": { "type": "object", "description": "JSON Schema fragment for the operation's arguments." },
+          "effects": { "type": "array", "items": { "type": "string" } },
+          "reversible": { "type": "boolean" },
+          "requiresConfirmation": { "type": "boolean" }
+        }
+      }
+    },
+
+    "intentDomains": {
+      "type": "array",
+      "description": "Advisory routing hints only. Never a substitute for operations, and carrying no execution semantics.",
+      "items": {
+        "enum": ["Query", "Extraction", "TemporalInterpretation", "ActionIntent", "Summarization", "Classification", "Recommendation"]
+      }
+    },
+
+    "safeMutations": {
+      "type": "object",
+      "description": "Authored. Which props an agent may change without altering behaviour.",
+      "additionalProperties": false,
+      "properties": {
+        "allowed": { "type": "array", "items": { "type": "string" } },
+        "forbidden": { "type": "array", "items": { "type": "string" } },
+        "rationale": { "type": "string" }
+      }
+    },
+
+    "examples": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "required": ["title", "file"],
+            "properties": {
+              "title": { "type": "string" },
+              "file": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        ]
+      }
+    },
+
+    "coverage": {
+      "type": "object",
+      "required": ["propsTotal", "propsDescribed", "describedPct"],
+      "additionalProperties": false,
+      "properties": {
+        "propsTotal": { "type": "integer", "minimum": 0 },
+        "propsDescribed": { "type": "integer", "minimum": 0 },
+        "describedPct": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "authoredSections": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/source/beta-components/accordion/passport.json

@@ -0,0 +1,259 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Accordion",
+    "folder": "accordion",
+    "exports": [
+      "Accordion",
+      "AccordionContext",
+      "AccordionItem"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.3.0",
+    "files": [
+      "core/index.ts",
+      "core/open.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Accordion.tsx",
+      "react/AccordionItem.tsx",
+      "react/context.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:ae02f988d3538cf6f78b9f3729cebe38b371f0a929f3c5570edcd543d3769d82"
+  },
+  "props": [
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<'root', string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "collapsible",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Allow the open panel to be closed again. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultValue",
+      "type": "other",
+      "typeText": "string[] | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "A second line under the title.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Replaces the chevron.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "iconPosition",
+      "type": "enum",
+      "values": [
+        "end",
+        "start"
+      ],
+      "typeText": "AccordionIconPosition | undefined",
+      "required": false,
+      "default": "end",
+      "origin": "derived",
+      "description": "Which side the chevron sits on. Default `end`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "items",
+      "type": "other",
+      "typeText": "readonly AccordionItemData[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Render these panels, or pass `<AccordionItem>` children.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "meta",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Something at the end of the header: a badge, a count.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Allow more than one panel open at a time. Default false.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onValueChange",
+      "type": "function",
+      "signature": "((value: string[]) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "AccordionSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "value",
+      "type": "other",
+      "typeText": "string[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Open panels, by value (controlled).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "contained",
+        "plain",
+        "separated"
+      ],
+      "typeText": "AccordionVariant | undefined",
+      "required": false,
+      "default": "separated",
+      "origin": "derived",
+      "description": "Default `separated`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "events": [
+    {
+      "name": "onValueChange",
+      "signature": "((value: string[]) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "header",
+    "title",
+    "description",
+    "icon",
+    "content",
+    "body"
+  ],
+  "states": [
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "contained",
+        "plain"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 19,
+    "propsDescribed": 10,
+    "describedPct": 53,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}