sdocs 0.0.53 → 0.0.54

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.54] - 2026-07-05
+
+### Added
+
+- **Stage alignment on previews and examples.** Two direction-aware
+  attributes (also settable per-kind in `content.docs` and on `[DOCS]`):
+  `align` — horizontal (`left`/`center`/`right`/`justify`) — and `alignY` —
+  vertical (`top`/`middle`/`bottom`/`justify`). sdocs maps each to the right
+  flex property for the current `direction`, so `align="center"` centers
+  horizontally in a row or a column; `justify` spreads items along the flow.
+- **`attributeRules(kind)` in `sdocs/language`** — the allowed attributes and
+  value shapes for a block kind, the single source of truth behind both
+  diagnostics and the VS Code extension's attribute completions.
+
 ## [0.0.53] - 2026-07-05
 
 ### Added

package/dist/language/index.d.ts

@@ -1,4 +1,4 @@
 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 { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type Sizing, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.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,4 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
 export { projectSdoc, } from './projection.js';
 export { segmentPageBody, } from './page-islands.js';
-export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';
+export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, attributeRules, } from './parser.js';

package/dist/language/parser.d.ts

@@ -13,6 +13,10 @@ export interface Sizing {
     direction: string | null;
     /** gap of preview/example stages */
     gap: string | null;
+    /** horizontal alignment of preview/example stage contents */
+    align: string | null;
+    /** vertical alignment of preview/example stage contents */
+    alignY: string | null;
     /** table-of-contents visibility (PAGE) */
     toc: boolean | null;
 }
@@ -88,6 +92,17 @@ export interface SdocDocument {
 export declare function normalizeBody(raw: string): string;
 /** Slug used for entity addressing: relPath + '#' + slug. */
 export declare function slugifyTitle(title: string): string;
+export interface AttrRule {
+    /** required | optional */
+    required: boolean;
+    /** expected value kind */
+    kind: 'string' | 'expression';
+    hint: string;
+}
+/** Allowed attributes and their value shapes for a block, keyed by kind
+ * ('DOCS'|'PAGE'|'LAYOUT'|'preview'|'example'). Single source of truth for
+ * both diagnostics and editor attribute completions. */
+export declare function attributeRules(kind: string): Record<string, AttrRule>;
 /**
  * Parse a preview args expression: a flat object literal whose values are
  * plain literals (strings, numbers, booleans). Anything richer belongs in

package/dist/language/parser.js

@@ -50,6 +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"' },
 };
 function sizingOf(attrs) {
     const toc = stringAttr(attrs, 'toc');
@@ -58,6 +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'),
         toc: toc === null ? null : toc === 'true',
     };
 }
@@ -92,6 +96,12 @@ const SUB_BLOCK_ATTR_RULES = {
         ...STAGE_LAYOUT_ATTR_RULES,
     },
 };
+/** Allowed attributes and their value shapes for a block, keyed by kind
+ * ('DOCS'|'PAGE'|'LAYOUT'|'preview'|'example'). Single source of truth for
+ * both diagnostics and editor attribute completions. */
+export function attributeRules(kind) {
+    return ENTITY_ATTR_RULES[kind] ?? SUB_BLOCK_ATTR_RULES[kind] ?? {};
+}
 function checkAttrs(owner, attrs, rules, ownerSpan, diagnostics) {
     for (const [name, value] of Object.entries(attrs)) {
         const rule = rules[name];

package/dist/server/config.js

@@ -15,7 +15,14 @@ const DEFAULTS = {
     },
     content: {
         page: { maxWidth: '1200px', padding: '32px', toc: true },
-        docs: { maxWidth: '1200px', padding: '16px', direction: 'row', gap: '16px' },
+        docs: {
+            maxWidth: '1200px',
+            padding: '16px',
+            direction: 'row',
+            gap: '16px',
+            align: 'left',
+            alignY: 'top',
+        },
         layout: { maxWidth: '100%', padding: '0px' },
     },
 };

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

@@ -28,6 +28,8 @@ export declare function generateIframeComponent(scriptPrelude: string, snippetBo
     padding: string;
     direction?: string;
     gap?: string;
+    align?: string;
+    alignY?: 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

@@ -84,19 +84,46 @@ function injectRootRef(snippetBody, componentName) {
 export function generateIframeComponent(scriptPrelude, snippetBody, stateNames = [], componentName, stage) {
     // The stage layout (config -> entity -> block cascade) applies here, inside
     // the iframe, so every consumer of the preview page gets it. Preview and
-    // example stages are flex containers (direction + gap); page and layout
-    // stages are flow-root blocks. Both contain child margins, so the height
-    // reported for iframe auto-sizing is exact.
+    // example stages are flex containers (direction + gap + alignment); page and
+    // 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
+    // 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.
+    const H = {
+        left: 'flex-start',
+        center: 'center',
+        right: 'flex-end',
+        justify: 'space-between',
+    };
+    const V = {
+        top: 'flex-start',
+        middle: 'center',
+        bottom: 'flex-end',
+        justify: 'space-between',
+    };
+    const flexStage = () => {
+        const h = H[stage.align ?? 'left'] ?? 'flex-start';
+        const v = V[stage.alignY ?? 'top'] ?? 'flex-start';
+        const isColumn = String(stage.direction).startsWith('column');
+        const justify = isColumn ? v : h;
+        let alignItems = isColumn ? h : v;
+        if (alignItems === 'space-between')
+            alignItems = 'stretch';
+        return [
+            'display: flex',
+            `flex-direction: ${stage.direction}`,
+            'flex-wrap: wrap',
+            `justify-content: ${justify}`,
+            `align-items: ${alignItems}`,
+            `gap: ${stage.gap}`,
+        ];
+    };
     const stageStyle = [
-        ...(stage?.direction
-            ? [
-                'display: flex',
-                `flex-direction: ${stage.direction}`,
-                'flex-wrap: wrap',
-                'align-items: flex-start',
-                `gap: ${stage.gap}`,
-            ]
-            : ['display: flow-root']),
+        ...(stage?.direction ? flexStage() : ['display: flow-root']),
         ...(stage ? [`padding: ${stage.padding}`] : []),
         ...(stage && stage.maxWidth !== '100%'
             ? [`max-width: ${stage.maxWidth}`, 'margin-inline: auto']

package/dist/types.d.ts

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

package/dist/vite.js

@@ -308,11 +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 flex the preview/example stages only
+                // direction/gap/align 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,
                     }
                     : {}),
             });

package/package.json

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