Merge branch 'main' into engineer/doctrine-8-fs-http-docs

Author: Goosterhof

docs/packages/dialog.md

@@ -167,6 +167,42 @@ dialog.open(
 
 The service supports `v-model` prop updates — if your dialog emits `update:modelValue` events, the internal state stays in sync.
 
+## Accessibility — Host ARIA Attributes
+
+Native `<dialog>` elements need an accessible name (and usually a description) so screen readers announce more than a generic "dialog". `dialog.open()` accepts a third options arg that applies ARIA attributes directly to the host `<dialog>` element — your inner component does not need to walk `closest('dialog')` from a template ref.
+
+```typescript
+dialog.open(
+    ConfirmDialog,
+    {title: 'Delete user?', message: 'This action cannot be undone.'},
+    {ariaLabelledBy: 'confirm-dialog-title', ariaDescribedBy: 'confirm-dialog-message'},
+);
+```
+
+```vue
+<!-- ConfirmDialog.vue — the ids match the host attributes above -->
+<template>
+    <div>
+        <h2 id="confirm-dialog-title">{{ title }}</h2>
+        <p id="confirm-dialog-message">{{ message }}</p>
+    </div>
+</template>
+```
+
+For dialogs without a visible title element, use `ariaLabel` instead:
+
+```typescript
+dialog.open(
+    IconOnlyDialog,
+    {
+        /* … */
+    },
+    {ariaLabel: 'Delete confirmation'},
+);
+```
+
+All three options are independent and optional — pass any combination. Options omitted leave the corresponding attribute off the `<dialog>` element entirely (no empty-string attributes).
+
 ## API Reference
 
 ### `createDialogService()`
@@ -175,12 +211,22 @@ Returns a dialog service. No parameters.
 
 ### Service Properties
 
-| Property                           | Type                                | Description                  |
-| ---------------------------------- | ----------------------------------- | ---------------------------- |
-| `open(component, props)`           | `(component, props) => void`        | Push a dialog onto the stack |
-| `closeAll()`                       | `() => void`                        | Clear the entire stack       |
-| `registerErrorMiddleware(handler)` | `(handler) => UnregisterMiddleware` | Register an error handler    |
-| `DialogContainerComponent`         | `Component`                         | Mount this in your app root  |
+| Property                           | Type                                                      | Description                  |
+| ---------------------------------- | --------------------------------------------------------- | ---------------------------- |
+| `open(component, props, options?)` | `(component, props, options?: DialogOpenOptions) => void` | Push a dialog onto the stack |
+| `closeAll()`                       | `() => void`                                              | Clear the entire stack       |
+| `registerErrorMiddleware(handler)` | `(handler) => UnregisterMiddleware`                       | Register an error handler    |
+| `DialogContainerComponent`         | `Component`                                               | Mount this in your app root  |
+
+### `DialogOpenOptions`
+
+```typescript
+interface DialogOpenOptions {
+    ariaLabel?: string; // sets aria-label on the host <dialog>
+    ariaLabelledBy?: string; // sets aria-labelledby on the host <dialog>
+    ariaDescribedBy?: string; // sets aria-describedby on the host <dialog>
+}
+```
 
 ### Error Handler Signature
 

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/fs-adapter-store",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "Reactive adapter-store pattern with domain state management and CRUD resource adapters",
     "homepage": "https://packages.script.nl/packages/adapter-store",
     "license": "MIT",
@@ -42,15 +42,15 @@
     },
     "devDependencies": {
         "@script-development/fs-helpers": "^0.1.0",
-        "@script-development/fs-http": "^0.1.0 || ^0.2.0",
+        "@script-development/fs-http": "^0.1.0 || ^0.2.0 || ^0.3.0",
         "@script-development/fs-loading": "^0.1.0",
         "@script-development/fs-storage": "^0.1.0",
         "happy-dom": "^20.9.0",
         "vue": "^3.5.33"
     },
     "peerDependencies": {
         "@script-development/fs-helpers": "^0.1.0",
-        "@script-development/fs-http": "^0.1.0 || ^0.2.0",
+        "@script-development/fs-http": "^0.1.0 || ^0.2.0 || ^0.3.0",
         "@script-development/fs-loading": "^0.1.0",
         "@script-development/fs-storage": "^0.1.0",
         "vue": "^3.5.33"

packages/adapter-store/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/fs-dialog",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Component-agnostic dialog stack service for Vue 3 — LIFO management with error middleware, you bring the component",
     "homepage": "https://packages.script.nl/packages/dialog",
     "license": "MIT",

packages/dialog/package.json

@@ -8,10 +8,20 @@ type UnregisterMiddleware = () => void;
 /** Error handler for dialog middleware chain. Return `false` to stop propagation. */
 export type DialogErrorHandler = (error: Error, context: {closeAll: () => void}) => boolean;
 
+/** Host-level options applied to the `<dialog>` element itself, not the inner component. */
+export interface DialogOpenOptions {
+    /** Sets `aria-label` on the host `<dialog>` element. */
+    ariaLabel?: string;
+    /** Sets `aria-labelledby` on the host `<dialog>` element. */
+    ariaLabelledBy?: string;
+    /** Sets `aria-describedby` on the host `<dialog>` element. */
+    ariaDescribedBy?: string;
+}
+
 /** Public API of a dialog service instance. */
 export interface DialogService {
     /** Open a component in a new dialog on top of the stack. */
-    open: <C extends Component>(component: C, props: ComponentProps<C>) => void;
+    open: <C extends Component>(component: C, props: ComponentProps<C>, options?: DialogOpenOptions) => void;
     /** Close all dialogs in the stack. */
     closeAll: () => void;
     /** Register an error middleware handler. Returns an unregister function. */
@@ -73,7 +83,7 @@ export const createDialogService = (): DialogService => {
         updateBodyScroll();
     };
 
-    const open = <C extends Component>(component: C, props: ComponentProps<C>): void => {
+    const open = <C extends Component>(component: C, props: ComponentProps<C>, options?: DialogOpenOptions): void => {
         const key = `dialog-${dialogId++}`;
         const rawComponent = markRaw(component);
 
@@ -87,6 +97,9 @@ export const createDialogService = (): DialogService => {
                 {
                     key,
                     style: DIALOG_STYLE,
+                    'aria-label': options?.ariaLabel,
+                    'aria-labelledby': options?.ariaLabelledBy,
+                    'aria-describedby': options?.ariaDescribedBy,
                     onCancel: (event: Event) => event.preventDefault(),
                     onClick: (event: MouseEvent) => {
                         if ((event.target as HTMLElement).tagName === 'DIALOG') {

packages/dialog/src/index.ts

@@ -817,6 +817,144 @@ describe('dialog service', () => {
         });
     });
 
+    describe('host ARIA attributes', () => {
+        it('should set aria-label on the dialog element when option is provided', async () => {
+            // Arrange
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(TestDialogContent, {title: 'Test'}, {ariaLabel: 'Confirm action'});
+            await nextTick();
+
+            // Assert
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-label')).toBe('Confirm action');
+        });
+
+        it('should set aria-labelledby on the dialog element when option is provided', async () => {
+            // Arrange
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(TestDialogContent, {title: 'Test'}, {ariaLabelledBy: 'dialog-title-id'});
+            await nextTick();
+
+            // Assert
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-labelledby')).toBe('dialog-title-id');
+        });
+
+        it('should set aria-describedby on the dialog element when option is provided', async () => {
+            // Arrange
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(TestDialogContent, {title: 'Test'}, {ariaDescribedBy: 'dialog-desc-id'});
+            await nextTick();
+
+            // Assert
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-describedby')).toBe('dialog-desc-id');
+        });
+
+        it('should set all three ARIA attributes simultaneously when all are provided', async () => {
+            // Arrange
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(
+                TestDialogContent,
+                {title: 'Test'},
+                {ariaLabel: 'overall-label', ariaLabelledBy: 'title-ref', ariaDescribedBy: 'desc-ref'},
+            );
+            await nextTick();
+
+            // Assert — each option maps to its dedicated host attribute, not aliased
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-label')).toBe('overall-label');
+            expect(dialog.attributes('aria-labelledby')).toBe('title-ref');
+            expect(dialog.attributes('aria-describedby')).toBe('desc-ref');
+        });
+
+        it('should not set ARIA host attributes when options are omitted', async () => {
+            // Arrange
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act — omit the options arg entirely (covers optional-chain falsy path)
+            service.open(TestDialogContent, {title: 'No ARIA'});
+            await nextTick();
+
+            // Assert — none of the ARIA host attributes are present on the dialog element
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-label')).toBeUndefined();
+            expect(dialog.attributes('aria-labelledby')).toBeUndefined();
+            expect(dialog.attributes('aria-describedby')).toBeUndefined();
+        });
+
+        it('should not set ARIA attributes that are absent from a partial options object', async () => {
+            // Arrange — provide only one ARIA option; the other two must remain absent.
+            // This guards against accidentally cross-wiring options to the wrong attribute.
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(TestDialogContent, {title: 'Test'}, {ariaLabelledBy: 'only-this'});
+            await nextTick();
+
+            // Assert
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-labelledby')).toBe('only-this');
+            expect(dialog.attributes('aria-label')).toBeUndefined();
+            expect(dialog.attributes('aria-describedby')).toBeUndefined();
+        });
+
+        it('should not forward ARIA host options into the inner component props', async () => {
+            // Arrange — host ARIA options must apply to the <dialog> element only,
+            // never leak into the rendered component's props.
+            const PropSpy = defineComponent({
+                props: {
+                    title: String,
+                    onClose: Function,
+                    ariaLabel: {type: String, default: 'untouched'},
+                    ariaLabelledBy: {type: String, default: 'untouched'},
+                    ariaDescribedBy: {type: String, default: 'untouched'},
+                },
+                render() {
+                    return h('div', {class: 'prop-spy'}, [
+                        h('span', {class: 'spy-label'}, this.ariaLabel),
+                        h('span', {class: 'spy-labelled-by'}, this.ariaLabelledBy),
+                        h('span', {class: 'spy-described-by'}, this.ariaDescribedBy),
+                    ]);
+                },
+            });
+
+            const service = createDialogService();
+            const wrapper = mount(service.DialogContainerComponent);
+
+            // Act
+            service.open(
+                PropSpy,
+                {title: 'Test'},
+                {ariaLabel: 'host-label', ariaLabelledBy: 'host-title', ariaDescribedBy: 'host-desc'},
+            );
+            await nextTick();
+
+            // Assert — inner component sees its prop defaults, host attributes sit on <dialog>
+            expect(wrapper.find('.spy-label').text()).toBe('untouched');
+            expect(wrapper.find('.spy-labelled-by').text()).toBe('untouched');
+            expect(wrapper.find('.spy-described-by').text()).toBe('untouched');
+            const dialog = wrapper.find('dialog');
+            expect(dialog.attributes('aria-label')).toBe('host-label');
+            expect(dialog.attributes('aria-labelledby')).toBe('host-title');
+            expect(dialog.attributes('aria-describedby')).toBe('host-desc');
+        });
+    });
+
     describe('dialog key uniqueness', () => {
         it('should generate unique keys for sequential dialogs', async () => {
             // Arrange

packages/dialog/tests/dialog.spec.ts

@@ -1,7 +1,7 @@
 {
     "name": "@script-development/fs-helpers",
-    "version": "0.1.1",
-    "description": "Tree-shakeable shared utility helpers: deep copy, type guards, and case conversion",
+    "version": "0.1.2",
+    "description": "Tree-shakeable shared utility helpers: deep copy, type guards, case conversion, and browser download",
     "homepage": "https://packages.script.nl/packages/helpers",
     "license": "MIT",
     "repository": {
@@ -43,6 +43,9 @@
     "dependencies": {
         "string-ts": "^2.3.1"
     },
+    "devDependencies": {
+        "happy-dom": "^20.9.0"
+    },
     "engines": {
         "node": ">=24.0.0"
     }

packages/helpers/package.json

@@ -0,0 +1,18 @@
+/**
+ * Triggers a browser download for a Blob.
+ *
+ * Creates a transient `<a>` element pointing at an object URL, dispatches a
+ * click, then revokes the URL. The browser's download UI captures its own
+ * reference during click(), so revoking immediately does not interrupt the
+ * in-flight download — it simply releases the blob reference held by the URL.
+ *
+ * Lives in `fs-helpers` rather than `fs-http` so the HTTP factory remains a
+ * transport-only library with no DOM coupling (fs-packages issue #59).
+ */
+export const triggerDownload = (blob: Blob, filename: string): void => {
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(blob);
+    link.download = filename;
+    link.click();
+    URL.revokeObjectURL(link.href);
+};