@situaction/traquiste-docs-kit 0.0.0-stage → 1.1.0

package/dist/vite/extractProps.js

@@ -0,0 +1,79 @@
+/** Reads component props from TypeScript sources (interfaces, JSDoc, defaults) — Node only */
+import ts from 'typescript';
+import { withCompilerOptions, withCustomConfig } from 'react-docgen-typescript';
+const PARSER_OPTIONS = {
+    // Unions of literals are expanded to their values instead of a type alias name
+    shouldExtractLiteralValuesFromEnum: true,
+    shouldRemoveUndefinedFromOptional: true,
+    savePropValueAsString: true,
+    // Inherited DOM / React props (ButtonHTMLAttributes, ViewProps…) would bury the component's own API
+    propFilter: (prop) => !prop.parent?.fileName.includes('node_modules'),
+};
+// Single quotes, as in the libraries' code style: "primary" → 'primary'
+const singleQuote = (literal) => literal.replace(/^"(.*)"$/, "'$1'");
+/** Removes outer parentheses added around optional function types: `(() => void)` → `() => void` */
+function unwrapParens(type) {
+    if (!type.startsWith('(') || !type.endsWith(')'))
+        return type;
+    let depth = 0;
+    for (let i = 0; i < type.length; i++) {
+        if (type[i] === '(')
+            depth++;
+        else if (type[i] === ')')
+            depth--;
+        // The first parenthesis closes before the end: they do not wrap the whole type
+        if (depth === 0 && i < type.length - 1)
+            return type;
+    }
+    return type.slice(1, -1);
+}
+function formatType(prop) {
+    const { type } = prop;
+    if (type.name === 'enum') {
+        const values = (type.value ?? []);
+        if (values.length)
+            return values.map((v) => singleQuote(v.value)).join(' | ');
+        return type.raw ?? type.name;
+    }
+    return unwrapParens(type.name)
+        // ReactElement<unknown, string | JSXElementConstructor<any>> → ReactElement
+        .replace(/ReactElement<[^<>]*(<[^<>]*>[^<>]*)*>/g, 'ReactElement');
+}
+function formatDefault(value, type) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const text = String(value);
+    // String defaults come without quotes: put them back when the prop holds strings
+    const isStringProp = type === 'string' || type.includes("'");
+    const isLiteral = /^(true|false|null|undefined|-?\d+(\.\d+)?|['"`].*)$/.test(text);
+    return isStringProp && !isLiteral ? `'${text}'` : text;
+}
+// JSDoc written as `/** text **/` leaves a trailing asterisk
+const cleanDescription = (text) => text.replace(/\s*\*+\s*$/, '').trim();
+function toPropDef(prop) {
+    const type = formatType(prop);
+    const def = formatDefault(prop.defaultValue?.value, type);
+    return {
+        name: prop.name,
+        type,
+        required: prop.required,
+        ...(def !== undefined ? { default: def } : {}),
+        description: cleanDescription(prop.description),
+    };
+}
+// docgen also reports exported helpers and constants (getBearingSector, MARKER_HEIGHT): keep PascalCase only
+const isComponentName = (name) => /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+function toComponentProps(docs) {
+    const result = {};
+    for (const doc of docs) {
+        if (isComponentName(doc.displayName))
+            result[doc.displayName] = Object.values(doc.props).map(toPropDef);
+    }
+    return result;
+}
+export function createPropsExtractor({ tsconfig } = {}) {
+    const parser = tsconfig
+        ? withCustomConfig(tsconfig, PARSER_OPTIONS)
+        : withCompilerOptions({ jsx: ts.JsxEmit.ReactJSX, esModuleInterop: true, skipLibCheck: true }, PARSER_OPTIONS);
+    return (files) => (files.length ? toComponentProps(parser.parse(files)) : {});
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from 'vite';
+export type { ComponentProps } from './extractProps.js';
+export interface DocgenOptions {
+    /** Component source files, relative to the Vite root — e.g. ['../src/components/**\/*.tsx'] */
+    include: string[];
+    /** Files to skip — stories and tests are always skipped */
+    exclude?: string[];
+    /** tsconfig used to read the components, relative to the Vite root */
+    tsconfig?: string;
+}
+/** Absolute paths of the files matching `include` minus `exclude` */
+export declare function findComponentFiles(root: string, include: string[], exclude?: string[]): Promise<string[]>;
+/**
+ * Exposes `virtual:traquiste-docs/props`, a `{ [componentName]: PropDef[] }` map to pass to
+ * `defineDocsConfig({ componentProps })`. Pages then use `props: 'auto'`.
+ */
+export declare function docgen(options: DocgenOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAA;AAIlD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAQD,qEAAqE;AACrE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnH;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAqDrD"}

package/dist/vite/index.js

@@ -0,0 +1,73 @@
+/** Vite plugin: generates component props tables from TypeScript sources — import from '@situaction/traquiste-docs-kit/vite' */
+import path from 'node:path';
+import { glob } from 'tinyglobby';
+import { createPropsExtractor } from './extractProps.js';
+const VIRTUAL_ID = 'virtual:traquiste-docs/props';
+const RESOLVED_ID = '\0' + VIRTUAL_ID;
+// Matched on absolute paths: glob `ignore` patterns are relative to the cwd, and components live
+// outside it (`../src/…`), so they would never apply
+const ALWAYS_EXCLUDED = /(\.(stories|test|spec)\.[^/\\]+$)|([/\\]node_modules[/\\])/;
+/** Absolute paths of the files matching `include` minus `exclude` */
+export async function findComponentFiles(root, include, exclude = []) {
+    const [matched, excluded] = await Promise.all([
+        glob(include, { cwd: root, absolute: true }),
+        exclude.length ? glob(exclude, { cwd: root, absolute: true }) : Promise.resolve([]),
+    ]);
+    const skip = new Set(excluded);
+    return matched.filter((file) => !skip.has(file) && !ALWAYS_EXCLUDED.test(file)).sort();
+}
+/**
+ * Exposes `virtual:traquiste-docs/props`, a `{ [componentName]: PropDef[] }` map to pass to
+ * `defineDocsConfig({ componentProps })`. Pages then use `props: 'auto'`.
+ */
+export function docgen(options) {
+    let root = process.cwd();
+    let files = [];
+    let props = {};
+    let extract;
+    let ready = null;
+    async function scan() {
+        files = await findComponentFiles(root, options.include, options.exclude);
+        props = extract(files);
+    }
+    const isIncluded = (file) => files.includes(path.resolve(file));
+    return {
+        name: 'traquiste-docs:docgen',
+        configResolved(config) {
+            root = config.root;
+            extract = createPropsExtractor({
+                tsconfig: options.tsconfig ? path.resolve(root, options.tsconfig) : undefined,
+            });
+        },
+        resolveId(id) {
+            return id === VIRTUAL_ID ? RESOLVED_ID : null;
+        },
+        async load(id) {
+            if (id !== RESOLVED_ID)
+                return null;
+            // Parsed once, on first import: a TypeScript program over all components takes a few seconds
+            ready ??= scan();
+            await ready;
+            return `export default ${JSON.stringify(props)}`;
+        },
+        configureServer(server) {
+            // Edit a component → re-read it alone; add or remove one → rescan everything
+            const refresh = async (file, rescan) => {
+                if (rescan)
+                    await scan();
+                else if (isIncluded(file))
+                    Object.assign(props, extract([path.resolve(file)]));
+                else
+                    return;
+                const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+                if (mod) {
+                    server.moduleGraph.invalidateModule(mod);
+                    server.ws.send({ type: 'full-reload' });
+                }
+            };
+            server.watcher.on('change', (file) => void refresh(file, false));
+            server.watcher.on('add', (file) => void refresh(file, true));
+            server.watcher.on('unlink', (file) => void refresh(file, true));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,113 @@
 {
   "name": "@situaction/traquiste-docs-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Documentation site engine shared by the Traquiste UI libraries (web and mobile)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./dist/vite/index.js"
+    },
+    "./client": {
+      "types": "./client.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "client.d.ts",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/styles && cp src/styles/*.css dist/styles/",
+    "build:playground": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "documentation",
+    "react",
+    "live-editor",
+    "traquiste"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/winoc/traq-ui-ste-docs-kit"
+  },
+  "bugs": {
+    "url": "https://bitbucket.org/winoc/traq-ui-ste-docs-kit/issues"
+  },
+  "author": "Situaction <dev@situaction.fr>",
+  "license": "MIT",
+  "homepage": "https://bitbucket.org/winoc/traq-ui-ste-docs-kit#readme",
+  "dependencies": {
+    "@babel/standalone": "^7.29.4",
+    "@monaco-editor/react": "^4.7.0",
+    "@phosphor-icons/react": "^2.1.10",
+    "react-docgen-typescript": "^2.4.0",
+    "react-router-dom": "^7.15.1",
+    "tinyglobby": "^0.2.17"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": ">=5.0.0",
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/babel__standalone": "^7.1.9",
+    "@types/node": "^24.12.3",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "react-native": "^0.83.6",
+    "react-native-web": "^0.21.4",
+    "semantic-release": "^25.0.3",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^8.0.12",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "@types/react": "$@types/react"
+  }
+}