@forsakringskassan/docs-live-example 1.3.0

package/LICENSE.md

@@ -0,0 +1,24 @@
+# The MIT License (MIT)
+
+Copyright © 2024 Försäkringskassan
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# `@forsakringskassan/docs-live-example`
+
+`live-example` är en Vue-komponent som används för att presentera ett levande exempel samt tillhörande markup för att reproducera exemplet.
+
+Komponenten består av tre ytor:
+
+-   exempelyta: innehåller det kompilerade exemplet.
+-   kontrollyta: innehåller de inmatningsfält som används för att konfigurera exemplet.
+-   kodyta: visar HTML-markup och Vue-template för exemplet (om Vue-komponenter används).
+
+Eftersom `live-example` kompileras i runtime så kan man direkt modifiera exemplet och den markup som visas genom att använda de inmatningsfält som lagts till i kontrollytan.
+
+## Användning
+
+Installera paketet genom att köra:
+
+`npm install --save-dev @forsakringskassan/docs-live-example`
+
+Om du använder `html-validate` bör du även uppdatera din `.htmlvalidate.json` med följande rader för att registrera `live-example` elementet:
+
+```json
+"extends": [
+    "@forsakringskassan/docs-live-example/htmlvalidate:recommended",
+],
+"plugins": [
+    "@forsakringskassan/docs-live-example/htmlvalidate"
+],
+```
+
+### Props
+
+#### `template`
+
+För att generera ett exempel så används `template` för att skicka in markup.
+
+#### `components` (optional)
+
+De Vue-komponenter som används i markup som skickas in till `template` måste läggas till i `components`.
+
+#### `livedata` (optional)
+
+Om exemplet behöver spara ett värde (till exempel `v-model`) så skickas detta in genom `livedata`.
+
+#### `livemethods` (optional)
+
+Om exemplet behöver köra en metod så skickas detta in genom `livemethods`.
+
+### Konfigurera exemplet
+
+För att skapa ett konfigurerbart exempel börjar vi med att skapa en ny komponent `AwesomeComponentLiveExample.vue`.
+Vi rekommenderar att använda `LiveExample` som suffix på alla live-exempel.
+
+Följande boilerplate kan användas:
+
+```vue
+<template>
+    <live-example :components :template :livedata>
+        <!-- Example configuration -->
+    </live-example>
+</template>
+
+<script lang="ts">
+import { defineComponent } from "vue";
+import { LiveExample } from "@forsakringskassan/docs-live-example";
+
+export default defineComponent({
+    name: "AwesomeComponentLiveExample",
+    components: { LiveExample },
+    data() {
+        return {};
+    },
+    computed: {
+        livedata(): unknown {
+            return {
+                /* data used by generated code */
+            };
+        },
+        components(): unknown {
+            return {
+                /* components used by generated code */
+            };
+        },
+        template(): string {
+            return /* HTML */ ` <div>Hello World!</div> `;
+        },
+    },
+});
+</script>
+```
+
+För att skapa en inställning lägger vi först in komponenter:
+
+```diff
+     <live-example :components :template :livedata>
++        <f-select-field v-model="tagName">
++            <template #label> Element </template>
++            <option value="div"> div </option>
++            <option value="p"> p </option>
++            <option value="em"> em </option>
++        </f-select-field>
++        <f-checkbox-field v-model="placeholderText" :value="true">
++            Use placeholder text
++        </f-checkbox-field>
+     </live-example>
+```
+
+```diff
+     data() {
+-        return {};
++        return {
++            tagName: "div",
++            placeholderText: false,
++        };
+     },
+```
+
+Därefter kan vi modifiera `template` att nyttja inställningar:
+
+```diff
+         template(): string {
+-            return /* HTML */ ` <div>Hello World!</div> `;
++            const { tagName, placeholderText } = this;
++            const message = placeholderText ? "Lorem ipsum dolor sit amet" : "Hello World!" ;
++            return /* HTML */ ` <${tagName}>${message}</${tagName}> `;
+         },
+```
+
+Det går också med fördel att använda `createElement` (se beskrivning längre ner):
+
+```diff
+         template(): string {
+-            return /* HTML */ ` <div>Hello World!</div> `;
++            const { tagName, placeholderText } = this;
++            const message = placeholderText ? "Lorem ipsum dolor sit amet" : "Hello World!" ;
++            return createElement(tagName, message);
+         },
+```
+
+## `createElement`
+
+A helper function to render the markup for the live example.
+
+```ts
+createElement(tagName);
+createElement(tagName, content);
+createElement(tagName, attributes);
+createElement(tagName, attributes, content);
+```
+
+Create markup for a simple element:
+
+```ts
+createElement("div");
+// <div>
+```
+
+Adding attributes:
+
+```ts
+createElement("div", { id: "my-awesome-id", class: ["foo", "bar"] });
+// <div id="my-awesome-id" class="foo bar">
+```
+
+Attributes can be:
+
+-   `string` - value is passed as-is: `{ key: "value" }` becomes `key="value"`.
+-   `number` - value is converted to string: `{ key: 12 }` becomes `key="12"`.
+-   `boolean` - key is set if value is true: `{ key: true }` becomes `key` and `{ key: false }` omits the attribute.
+-   `Array` - each non-empty item is joined: `{ key: ["foo", "bar"] }` becomes `key="foo bar"`.
+-   `Object` - nests attributes: `{ data: { key: "value" } }` becomes `data-key="value"`.
+-   `null` and `undefined` are omitted from its context, e.g. `{ key: null }` `{ key: [null] ` and `{ key: { value: null } }` are all omitted.
+
+Content can be added:
+
+```ts
+createElement("div", "lorem ipsum");
+// <div> lorem ipsum </div>
+
+createElement("div", [
+    createElement("h1", "My Awesome Heading"),
+    createElement("p", ["Lorem ipsum", "dolor sit amet"]),
+]);
+// <div> <h1> My Awesome Heading </h1> <p> Lorem ipsum dolor sit amet </p> </div>
+```
+
+Combined:
+
+```ts
+createElement("div", { id: "foo" }, "lorem ipsum");
+// <div id="foo"> lorem ipsum </div>
+```

package/dist/LiveCode.d.ts

@@ -0,0 +1,36 @@
+declare const _default: import("vue").DefineComponent<{
+    template: {
+        type: StringConstructor;
+        required: true;
+    };
+    components: {
+        type: ObjectConstructor;
+        required: true;
+    };
+    livedata: {
+        type: ObjectConstructor;
+        required: true;
+    };
+    livemethods: {
+        type: ObjectConstructor;
+        required: true;
+    };
+}, unknown, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+    template: {
+        type: StringConstructor;
+        required: true;
+    };
+    components: {
+        type: ObjectConstructor;
+        required: true;
+    };
+    livedata: {
+        type: ObjectConstructor;
+        required: true;
+    };
+    livemethods: {
+        type: ObjectConstructor;
+        required: true;
+    };
+}>>, {}, {}>;
+export default _default;

package/dist/LiveExample.vue.d.ts

@@ -0,0 +1,62 @@
+import { type ExpandAnimation } from "./expand-animation";
+declare const _default: import("vue").DefineComponent<{
+    template: {
+        type: StringConstructor;
+        required: true;
+    };
+    components: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+    livedata: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+    livemethods: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+}, unknown, {
+    idPrefix: string;
+    codeLanguage: string;
+    codeExpand: ExpandAnimation;
+}, {
+    isVue(): boolean;
+    codeToggleText(): string;
+    exampleElement(): HTMLElement;
+    expandableElement(): HTMLElement;
+    templateElement(): HTMLElement;
+}, {
+    onToggleCode(): void;
+    compileCode(): void;
+    compileVue(): Promise<void>;
+    compileHTML(): Promise<void>;
+}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+    template: {
+        type: StringConstructor;
+        required: true;
+    };
+    components: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+    livedata: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+    livemethods: {
+        type: ObjectConstructor;
+        required: false;
+        default: () => {};
+    };
+}>>, {
+    components: Record<string, any>;
+    livedata: Record<string, any>;
+    livemethods: Record<string, any>;
+}, {}>;
+export default _default;

package/dist/create-element.d.ts

@@ -0,0 +1,9 @@
+export type PlainValue = string | number | boolean | null | undefined;
+export interface Attributes {
+    [key: string]: PlainValue | PlainValue[] | Attributes;
+}
+export type Children = string | string[];
+export declare function createElement(tagName: string): string;
+export declare function createElement(tagName: string, children: Children): string;
+export declare function createElement(tagName: string, attrs: Attributes): string;
+export declare function createElement(tagName: string, attrs: Attributes, children: Children): string;

package/dist/expand-animation.d.ts

@@ -0,0 +1,5 @@
+export interface ExpandAnimation {
+    readonly isOpen: boolean;
+    toggle(): void;
+}
+export declare function expandAnimation(element: HTMLElement): ExpandAnimation;

package/dist/index.css

@@ -0,0 +1,7 @@
+/* sfc-style:/home/runner/work/docs-live-example/docs-live-example/src/LiveExample.vue?type=style&index=0 */
+.collapsed[data-v-f5e7ab48] {
+  display: none;
+}
+.collapsed[aria-expanded=true][data-v-f5e7ab48] {
+  display: block;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default as LiveExample } from "./LiveExample.vue";