sdocs 0.0.54 → 0.0.56

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.56] - 2026-07-05
+
+### Added
+
+- **`configSchema` in `sdocs/language`** — a structured description of the
+  `sdocs.config.*` shape (keys, documentation, and value enums) mirroring
+  `SdocsConfig`. Editor tooling reads it to complete the config file in
+  projects that don't install `sdocs`, so config completion can't drift from
+  the config type.
+
+## [0.0.55] - 2026-07-05
+
+### Changed
+
+- **Renamed the stage alignment attributes** `align`/`alignY` (added in
+  0.0.54) to **`contentX`**/**`contentY`** — for horizontal/vertical content
+  alignment on `[preview]`/`[example]` and their `content.docs` and `[DOCS]`
+  defaults. Values and direction-aware behavior are unchanged.
+
 ## [0.0.54] - 2026-07-05
 
 ### Added

package/dist/language/config-schema.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A structured description of the `sdocs.config.*` shape, mirroring the
+ * `SdocsConfig` type. Editor tooling consumes this to offer key and value
+ * completions in projects that don't install `sdocs` (where the TypeScript
+ * type isn't resolvable). Keep it in step with `SdocsConfig` in `types.ts`.
+ */
+/** One config key: how to present, insert, and (for enums) value-complete it. */
+export interface ConfigFieldSchema {
+    /** Short type hint shown as the completion detail, e.g. `'string | string[]'`. */
+    detail: string;
+    /** Markdown documentation for the key. */
+    doc: string;
+    /** Snippet inserted after the key name — includes the `:` and a tabstop. */
+    insert: string;
+    /** Allowed values, for value-position completion. */
+    values?: string[];
+    /** Whether `values` are strings (quoted on insert) or literals (inserted bare). */
+    quoted?: boolean;
+    /** Nested object schema, when this key holds an object. */
+    object?: ConfigSchema;
+}
+/** A config object shape: its keys mapped to their field descriptions. */
+export type ConfigSchema = Record<string, ConfigFieldSchema>;
+/** The `sdocs.config.*` schema, rooted at the exported config object. */
+export declare const configSchema: ConfigSchema;

package/dist/language/config-schema.js

@@ -0,0 +1,131 @@
+/**
+ * A structured description of the `sdocs.config.*` shape, mirroring the
+ * `SdocsConfig` type. Editor tooling consumes this to offer key and value
+ * completions in projects that don't install `sdocs` (where the TypeScript
+ * type isn't resolvable). Keep it in step with `SdocsConfig` in `types.ts`.
+ */
+// Sizing knobs shared by the page/docs/layout content objects.
+const maxWidth = {
+    detail: 'string',
+    doc: 'Content column max width — any CSS length (`1200px`, `80ch`, `100%`).',
+    insert: ": '$0'",
+};
+const padding = {
+    detail: 'string',
+    doc: 'Space around the content — any CSS padding shorthand (`16px`, `1rem 2rem`).',
+    insert: ": '$0'",
+};
+// Stage-layout knobs shared by the docs preview/example stages.
+const direction = {
+    detail: "'row' | 'column'",
+    doc: 'Preview/example stage `flex-direction`. Default: `row`.',
+    insert: ": '${0:row}'",
+    values: ['row', 'column', 'row-reverse', 'column-reverse'],
+    quoted: true,
+};
+const gap = {
+    detail: 'string',
+    doc: 'Gap between stage items — any CSS length. Default: `16px`.',
+    insert: ": '$0'",
+};
+const contentX = {
+    detail: "'left' | 'center' | 'right' | 'justify'",
+    doc: 'Horizontal alignment of stage contents. Default: `left`.',
+    insert: ": '${0:left}'",
+    values: ['left', 'center', 'right', 'justify'],
+    quoted: true,
+};
+const contentY = {
+    detail: "'top' | 'middle' | 'bottom' | 'justify'",
+    doc: 'Vertical alignment of stage contents. Default: `top`.',
+    insert: ": '${0:top}'",
+    values: ['top', 'middle', 'bottom', 'justify'],
+    quoted: true,
+};
+/** The `sdocs.config.*` schema, rooted at the exported config object. */
+export const configSchema = {
+    include: {
+        detail: 'string | string[]',
+        doc: 'Glob pattern(s) locating your `.sdoc` files. Default: `./src/**/*.sdoc`.',
+        insert: ": ['$0']",
+    },
+    port: {
+        detail: 'number',
+        doc: 'Dev server port. Default: `3000`.',
+        insert: ': ${0:3000}',
+    },
+    open: {
+        detail: 'boolean',
+        doc: 'Open the browser when the dev server starts. Default: `false`.',
+        insert: ': ${0:false}',
+        values: ['true', 'false'],
+    },
+    css: {
+        detail: 'string | Record<string, string>',
+        doc: 'CSS loaded inside preview iframes — a single stylesheet path, or a map of named stylesheets to switch between.',
+        insert: ": '$0'",
+    },
+    logo: {
+        detail: 'string',
+        doc: 'Sidebar logo text. Default: `sdocs`.',
+        insert: ": '${0:sdocs}'",
+    },
+    icon: {
+        detail: 'string | false',
+        doc: "Sidebar logo icon: `'sdocs'` for the built-in mascot, an image URL, or `false` to hide it. Default: `'sdocs'`.",
+        insert: ": '${0:sdocs}'",
+        values: ['sdocs'],
+        quoted: true,
+    },
+    sidebar: {
+        detail: 'object',
+        doc: 'Sidebar ordering and default-expanded folders.',
+        insert: ': {\n\t$0\n}',
+        object: {
+            order: {
+                detail: 'Record<string, string[]>',
+                doc: "Per-folder sort overrides. Keys are folder paths (`'root'` for the top level); `'*'` stands for unlisted items.",
+                insert: ': {\n\t$0\n}',
+            },
+            open: {
+                detail: 'string[]',
+                doc: 'Folders expanded by default on load.',
+                insert: ': [$0]',
+            },
+        },
+    },
+    content: {
+        detail: 'object',
+        doc: 'Content presentation per entity kind. Entity and block attributes override these.',
+        insert: ': {\n\t$0\n}',
+        object: {
+            page: {
+                detail: 'object',
+                doc: '`[PAGE]` content. Defaults: `maxWidth` `1200px`, `padding` `32px`, `toc` `true`.',
+                insert: ': {\n\t$0\n}',
+                object: {
+                    maxWidth,
+                    padding,
+                    toc: {
+                        detail: 'boolean',
+                        doc: 'Show the page table of contents. Default: `true`.',
+                        insert: ': ${0:true}',
+                        values: ['true', 'false'],
+                    },
+                },
+            },
+            docs: {
+                detail: 'object',
+                doc: '`[DOCS]` pages. `maxWidth` is the content column; `padding`/`direction`/`gap`/`contentX`/`contentY` are the default preview & example stage layout.',
+                insert: ': {\n\t$0\n}',
+                object: { maxWidth, padding, direction, gap, contentX, contentY },
+            },
+            layout: {
+                detail: 'object',
+                doc: '`[LAYOUT]` stages. Defaults: `maxWidth` `100%`, `padding` `0px`.',
+                insert: ': {\n\t$0\n}',
+                object: { maxWidth, padding },
+            },
+        },
+    },
+};

package/dist/language/index.d.ts

@@ -1,4 +1,5 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, type Span, type EntityKind, type SubBlockKind, type AttrValue, type Attrs, type SubBlock, type Entity, type TagBlock, type ScanError, type SdocFile, } from './scanner.js';
 export { projectSdoc, type SdocProjection, type ProjectedLineKind, } from './projection.js';
 export { segmentPageBody, type PageSegment, } from './page-islands.js';
+export { configSchema, type ConfigSchema, type ConfigFieldSchema, } from './config-schema.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, attributeRules, type AttrRule, type ArgValue, type Sizing, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';

package/dist/language/index.js

@@ -1,4 +1,5 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
 export { projectSdoc, } from './projection.js';
 export { segmentPageBody, } from './page-islands.js';
+export { configSchema, } from './config-schema.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, attributeRules, } from './parser.js';

package/dist/language/parser.d.ts

@@ -14,9 +14,9 @@ export interface Sizing {
     /** gap of preview/example stages */
     gap: string | null;
     /** horizontal alignment of preview/example stage contents */
-    align: string | null;
+    contentX: string | null;
     /** vertical alignment of preview/example stage contents */
-    alignY: string | null;
+    contentY: string | null;
     /** table-of-contents visibility (PAGE) */
     toc: boolean | null;
 }

package/dist/language/parser.js

@@ -50,8 +50,8 @@ const SIZING_ATTR_RULES = {
 const STAGE_LAYOUT_ATTR_RULES = {
     direction: { required: false, kind: 'string', hint: 'direction="column"' },
     gap: { required: false, kind: 'string', hint: 'gap="16px"' },
-    align: { required: false, kind: 'string', hint: 'align="center"' },
-    alignY: { required: false, kind: 'string', hint: 'alignY="middle"' },
+    contentX: { required: false, kind: 'string', hint: 'contentX="center"' },
+    contentY: { required: false, kind: 'string', hint: 'contentY="middle"' },
 };
 function sizingOf(attrs) {
     const toc = stringAttr(attrs, 'toc');
@@ -60,8 +60,8 @@ function sizingOf(attrs) {
         padding: stringAttr(attrs, 'padding'),
         direction: stringAttr(attrs, 'direction'),
         gap: stringAttr(attrs, 'gap'),
-        align: stringAttr(attrs, 'align'),
-        alignY: stringAttr(attrs, 'alignY'),
+        contentX: stringAttr(attrs, 'contentX'),
+        contentY: stringAttr(attrs, 'contentY'),
         toc: toc === null ? null : toc === 'true',
     };
 }

package/dist/server/config.js

@@ -20,8 +20,8 @@ const DEFAULTS = {
             padding: '16px',
             direction: 'row',
             gap: '16px',
-            align: 'left',
-            alignY: 'top',
+            contentX: 'left',
+            contentY: 'top',
         },
         layout: { maxWidth: '100%', padding: '0px' },
     },

package/dist/server/snippet-compiler.d.ts

@@ -28,8 +28,8 @@ export declare function generateIframeComponent(scriptPrelude: string, snippetBo
     padding: string;
     direction?: string;
     gap?: string;
-    align?: string;
-    alignY?: string;
+    contentX?: string;
+    contentY?: string;
 }): string;
 /** The JS that boots a preview page: mount the wrapper + parent-frame messaging. */
 export declare function generateMountScript(iframeComponentId: string): string;

package/dist/server/snippet-compiler.js

@@ -88,8 +88,8 @@ export function generateIframeComponent(scriptPrelude, snippetBody, stateNames =
     // layout stages are flow-root blocks. Both contain child margins, so the
     // height reported for iframe auto-sizing is exact.
     //
-    // align/alignY are *physical* (horizontal/vertical); which flex property
-    // each drives depends on direction. The flow axis (main) takes
+    // contentX/contentY are *physical* (horizontal/vertical); which flex
+    // property each drives depends on direction. The flow axis (main) takes
     // justify-content, the other (cross) takes align-items — and align-items
     // has no distribution value, so a 'justify' that lands on the cross axis
     // falls back to stretch.
@@ -106,8 +106,8 @@ export function generateIframeComponent(scriptPrelude, snippetBody, stateNames =
         justify: 'space-between',
     };
     const flexStage = () => {
-        const h = H[stage.align ?? 'left'] ?? 'flex-start';
-        const v = V[stage.alignY ?? 'top'] ?? 'flex-start';
+        const h = H[stage.contentX ?? 'left'] ?? 'flex-start';
+        const v = V[stage.contentY ?? 'top'] ?? 'flex-start';
         const isColumn = String(stage.direction).startsWith('column');
         const justify = isColumn ? v : h;
         let alignItems = isColumn ? h : v;

package/dist/types.d.ts

@@ -35,9 +35,9 @@ export interface SdocsConfig {
             /** Stage gap. Default: '16px' */
             gap?: string;
             /** Horizontal alignment of stage contents: 'left'|'center'|'right'|'justify'. Default: 'left' */
-            align?: string;
+            contentX?: string;
             /** Vertical alignment of stage contents: 'top'|'middle'|'bottom'. Default: 'top' */
-            alignY?: string;
+            contentY?: string;
         };
         /** [LAYOUT] stages. Defaults: maxWidth '100%', padding '0px'. */
         layout?: ContentSizing;
@@ -52,13 +52,13 @@ export interface ContentSizing {
 export interface StageLayout {
     maxWidth: string;
     padding: string;
-    /** flex-direction + gap + align; set for preview/example stages only */
+    /** flex-direction + gap + contentX; set for preview/example stages only */
     direction?: string;
     gap?: string;
     /** horizontal ('left'|'center'|'right'|'justify') — mapped by direction */
-    align?: string;
+    contentX?: string;
     /** vertical ('top'|'middle'|'bottom') — mapped by direction */
-    alignY?: string;
+    contentY?: string;
 }
 /** Resolved config with all defaults applied */
 export interface ResolvedSdocsConfig {
@@ -79,8 +79,8 @@ export interface ResolvedSdocsConfig {
         docs: Required<ContentSizing> & {
             direction: string;
             gap: string;
-            align: string;
-            alignY: string;
+            contentX: string;
+            contentY: string;
         };
         layout: Required<ContentSizing>;
     };

package/dist/vite.js

@@ -308,13 +308,13 @@ export function sdocsPlugin(userConfig) {
                 maxWidth: block?.maxWidth ??
                     (entity.kind === 'LAYOUT' ? (entity.sizing.maxWidth ?? kindDefaults.maxWidth) : '100%'),
                 padding: block?.padding ?? entity.sizing.padding ?? kindDefaults.padding,
-                // direction/gap/align flex the preview/example stages only
+                // direction/gap/contentX flex the preview/example stages only
                 ...(entity.kind === 'DOCS' && block
                     ? {
                         direction: block.direction ?? entity.sizing.direction ?? config.content.docs.direction,
                         gap: block.gap ?? entity.sizing.gap ?? config.content.docs.gap,
-                        align: block.align ?? entity.sizing.align ?? config.content.docs.align,
-                        alignY: block.alignY ?? entity.sizing.alignY ?? config.content.docs.alignY,
+                        contentX: block.contentX ?? entity.sizing.contentX ?? config.content.docs.contentX,
+                        contentY: block.contentY ?? entity.sizing.contentY ?? config.content.docs.contentY,
                     }
                     : {}),
             });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sdocs",
-	"version": "0.0.54",
+	"version": "0.0.56",
 	"description": "A lightweight documentation tool for Svelte 5 components",
 	"type": "module",
 	"license": "MIT",