@cas-smartdesign/element-preview 0.2.1

package/npm-third-party-licenses.json

@@ -0,0 +1,187 @@
+{
+    "@cypress/vite-dev-server@5.0.7": {
+        "licenses": "MIT",
+        "repository": "https://github.com/cypress-io/cypress",
+        "licenseUrl": "https://github.com/cypress-io/cypress/tree/develop/npm/vite-dev-server#readme"
+    },
+    "@rollup/plugin-node-resolve@15.2.3": {
+        "licenses": "MIT",
+        "repository": "https://github.com/rollup/plugins",
+        "licenseUrl": "https://github.com/rollup/plugins/raw/HEAD/LICENSE"
+    },
+    "@types/node@20.10.6": {
+        "licenses": "MIT",
+        "repository": "https://github.com/DefinitelyTyped/DefinitelyTyped",
+        "licenseUrl": "https://github.com/DefinitelyTyped/DefinitelyTyped/raw/HEAD/LICENSE"
+    },
+    "@types/postcss-prefix-selector@1.16.3": {
+        "licenses": "MIT",
+        "repository": "https://github.com/DefinitelyTyped/DefinitelyTyped",
+        "licenseUrl": "https://github.com/DefinitelyTyped/DefinitelyTyped/raw/HEAD/LICENSE"
+    },
+    "@typescript-eslint/eslint-plugin@6.17.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/typescript-eslint/typescript-eslint",
+        "licenseUrl": "https://github.com/typescript-eslint/typescript-eslint/raw/HEAD/LICENSE"
+    },
+    "@typescript-eslint/parser@6.17.0": {
+        "licenses": "BSD-2-Clause",
+        "repository": "https://github.com/typescript-eslint/typescript-eslint",
+        "licenseUrl": "https://github.com/typescript-eslint/typescript-eslint/raw/HEAD/LICENSE"
+    },
+    "@vitest/coverage-v8@1.1.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/vitest-dev/vitest",
+        "licenseUrl": "https://github.com/vitest-dev/vitest/raw/HEAD/LICENSE"
+    },
+    "@vitest/ui@1.1.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/vitest-dev/vitest",
+        "licenseUrl": "https://github.com/vitest-dev/vitest/raw/HEAD/LICENSE"
+    },
+    "axe-core@4.8.3": {
+        "licenses": "MPL-2.0",
+        "repository": "https://github.com/dequelabs/axe-core",
+        "licenseUrl": "https://github.com/dequelabs/axe-core/raw/HEAD/LICENSE"
+    },
+    "cypress-axe@1.5.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/component-driven/cypress-axe",
+        "licenseUrl": "https://github.com/component-driven/cypress-axe/raw/HEAD/License.md"
+    },
+    "cypress-real-events@1.13.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/dmtrKovalenko/cypress-real-events",
+        "licenseUrl": "https://github.com/dmtrKovalenko/cypress-real-events"
+    },
+    "cypress@13.6.2": {
+        "licenses": "MIT",
+        "repository": "https://github.com/cypress-io/cypress",
+        "licenseUrl": "https://cypress.io"
+    },
+    "esbuild@0.19.11": {
+        "licenses": "MIT",
+        "repository": "https://github.com/evanw/esbuild",
+        "licenseUrl": "https://github.com/evanw/esbuild/raw/HEAD/LICENSE.md"
+    },
+    "eslint-config-google@0.14.0": {
+        "licenses": "Apache-2.0",
+        "repository": "https://github.com/google/eslint-config-google",
+        "licenseUrl": "https://github.com/google/eslint-config-google/raw/HEAD/LICENSE"
+    },
+    "eslint-config-prettier@9.1.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/prettier/eslint-config-prettier",
+        "licenseUrl": "https://github.com/prettier/eslint-config-prettier/raw/HEAD/LICENSE"
+    },
+    "eslint@8.56.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/eslint/eslint",
+        "licenseUrl": "https://github.com/eslint/eslint/raw/HEAD/LICENSE"
+    },
+    "github-markdown-css@5.5.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/sindresorhus/github-markdown-css",
+        "licenseUrl": "https://github.com/sindresorhus/github-markdown-css/raw/HEAD/license"
+    },
+    "highlight.js@11.9.0": {
+        "licenses": "BSD-3-Clause",
+        "repository": "https://github.com/highlightjs/highlight.js",
+        "licenseUrl": "https://github.com/highlightjs/highlight.js/raw/HEAD/LICENSE"
+    },
+    "junit-report-builder@3.1.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/davidparsson/junit-report-builder",
+        "licenseUrl": "https://github.com/davidparsson/junit-report-builder/raw/HEAD/LICENSE"
+    },
+    "lint-staged@15.2.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/okonet/lint-staged",
+        "licenseUrl": "https://github.com/okonet/lint-staged/raw/HEAD/LICENSE"
+    },
+    "marked@11.1.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/markedjs/marked",
+        "licenseUrl": "https://github.com/markedjs/marked/raw/HEAD/LICENSE.md"
+    },
+    "postcss-prefix-selector@1.16.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/RadValentin/postcss-prefix-selector",
+        "licenseUrl": "https://github.com/RadValentin/postcss-prefix-selector/raw/HEAD/LICENSE"
+    },
+    "postcss@8.4.32": {
+        "licenses": "MIT",
+        "repository": "https://github.com/postcss/postcss",
+        "licenseUrl": "https://github.com/postcss/postcss/raw/HEAD/LICENSE"
+    },
+    "prettier@3.1.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/prettier/prettier",
+        "licenseUrl": "https://github.com/prettier/prettier/raw/HEAD/LICENSE"
+    },
+    "resolve-pkg@2.0.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/sindresorhus/resolve-pkg",
+        "licenseUrl": "https://github.com/sindresorhus/resolve-pkg/raw/HEAD/license"
+    },
+    "sass@1.69.6": {
+        "licenses": "MIT",
+        "repository": "https://github.com/sass/dart-sass",
+        "licenseUrl": "https://github.com/sass/dart-sass/raw/HEAD/LICENSE"
+    },
+    "stylelint-config-recommended-scss@14.0.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/stylelint-scss/stylelint-config-recommended-scss",
+        "licenseUrl": "https://github.com/stylelint-scss/stylelint-config-recommended-scss/raw/HEAD/LICENSE"
+    },
+    "stylelint-config-standard@36.0.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/stylelint/stylelint-config-standard",
+        "licenseUrl": "https://github.com/stylelint/stylelint-config-standard/raw/HEAD/LICENSE"
+    },
+    "stylelint-scss@6.0.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/stylelint-scss/stylelint-scss",
+        "licenseUrl": "https://github.com/stylelint-scss/stylelint-scss/raw/HEAD/LICENSE"
+    },
+    "stylelint@16.1.0": {
+        "licenses": "MIT",
+        "repository": "https://github.com/stylelint/stylelint",
+        "licenseUrl": "https://github.com/stylelint/stylelint/raw/HEAD/LICENSE"
+    },
+    "tsup@8.0.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/egoist/tsup",
+        "licenseUrl": "https://github.com/egoist/tsup/raw/HEAD/LICENSE"
+    },
+    "turbo@1.11.2": {
+        "licenses": "MPL-2.0",
+        "repository": "https://github.com/vercel/turbo",
+        "licenseUrl": "https://github.com/vercel/turbo/raw/HEAD/LICENSE"
+    },
+    "typescript@5.3.3": {
+        "licenses": "Apache-2.0",
+        "repository": "https://github.com/Microsoft/TypeScript",
+        "licenseUrl": "https://github.com/Microsoft/TypeScript/raw/HEAD/LICENSE.txt"
+    },
+    "vite-tsconfig-paths@4.2.3": {
+        "licenses": "MIT",
+        "repository": "https://github.com/aleclarson/vite-tsconfig-paths",
+        "licenseUrl": "https://github.com/aleclarson/vite-tsconfig-paths/raw/HEAD/LICENSE"
+    },
+    "vite@5.0.10": {
+        "licenses": "MIT",
+        "repository": "https://github.com/vitejs/vite",
+        "licenseUrl": "https://github.com/vitejs/vite/raw/HEAD/LICENSE.md"
+    },
+    "vitest@1.1.1": {
+        "licenses": "MIT",
+        "repository": "https://github.com/vitest-dev/vitest",
+        "licenseUrl": "https://github.com/vitest-dev/vitest/raw/HEAD/LICENSE.md"
+    },
+    "yargs@17.7.2": {
+        "licenses": "MIT",
+        "repository": "https://github.com/yargs/yargs",
+        "licenseUrl": "https://github.com/yargs/yargs/raw/HEAD/LICENSE"
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@cas-smartdesign/element-preview",
+  "version": "0.2.1",
+  "description": "An element which encapsulates the look and feel for all element previews in the documentation",
+  "main": "dist/element-preview-with-externals.js",
+  "module": "dist/element-preview.mjs",
+  "types": "dist/element-preview.d.ts",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "dist",
+    "npm-third-party-licenses.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/postcss-prefix-selector": "^1.16.3",
+    "highlight.js": "^11.9.0",
+    "postcss": "^8.4.32",
+    "postcss-prefix-selector": "^1.16.0",
+    "@cas-smartdesign/license-generator": "^1.6.1"
+  },
+  "scripts": {
+    "version": "pnpm version",
+    "generate-declaration": "tsc -p tsconfig.types.json",
+    "build:no-license": "vite build && pnpm generate-declaration && vite build --mode documentation",
+    "build": "pnpm generate-license && pnpm build:no-license",
+    "watch": "vite build --watch",
+    "dev": "vite",
+    "generate-license": "sd-license-generator --r ../../"
+  }
+}

package/readme.md

@@ -0,0 +1,149 @@
+# @cas-smartdesign/element-preview
+
+A helper library that can be used to include examples in elements documentation with preview and source code(s).
+
+## Disclaimer
+
+> The tool is made for internal use, its API may change in the future.
+>
+> Please keep this in mind when using it.
+
+## Usage
+
+- Install `@cas-smartdesign/element-preview` as devDependency
+- Add the path alias. See more [below](#package-and-module-resolution).
+- Create the source code for the example
+  - Readme (with a brief description)
+  - HTML
+  - CSS (optional)
+  - Typescript (optional)
+- Create an index.ts that describes the example and its components
+- Create a `<div>` with `examples` id or have an `## Examples` section in the `readme.md`.
+  This will be the container for the examples
+- Call `initializeExamples` of `element-preview`
+
+## Package and module resolution
+
+By default the documented package and its modules cannot be referenced as the end user would do it:
+
+```
+import { ComboBox } from "@cas-smartdesign/combobox"
+```
+
+In order to make this work, the `tsconfig.json` should be extended with `baseUrl` and `paths` aliases:
+
+```
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@cas-smartdesign/combo-box": [
+        "./combo-box.ts"
+      ]
+    }
+  }
+}
+```
+
+For other use cases, the `///` character sequence can be used to replace lines on the UI
+
+```
+const s = "Runtime code"; /// const s = "Code for the UI";
+```
+
+It can be also used to show something only in the documentation or execute only when generating the preview.
+
+```
+const s = "This will be executed when generating the preview"; ///
+
+/// const s = "This will be shown only in the documentation";
+```
+
+## Example
+
+**Folder structure**
+
+```
+docs
+ ├ examples
+ |  └ sample-usage
+ |     ├ example.css
+ |     ├ example.html
+ |     ├ example.md
+ |     ├ example.ts
+ |     └ index.ts
+ ├ doc.html
+ └ doc.ts
+```
+
+**doc.ts**
+
+```typescript
+import "!style-loader!css-loader!github-markdown-css/github-markdown-light.css";
+import { initializeExamples } from "@cas-smartdesign/element-preview";
+
+document.querySelector("#markdown-container").innerHTML = require("../readme.md").default as string;
+initializeExamples(require.context("./examples", true, /index.ts/, "eager"), document.body);
+```
+
+**index.ts**
+
+```typescript
+import { ExampleDescription } from "@cas-smartdesign/element-preview";
+
+const example: ExampleDescription = {
+    mainContent: require("./example.html?raw")
+    description: require("./example.md").default as string,
+    initializer: {
+        content: require("!raw-loader!./example.ts").default,
+        type: "typescript",
+        initialize: () => require("./example.ts"),
+    },
+    css: require("!raw-loader!./example.css").default,
+};
+
+export default example;
+```
+
+**example.md**
+
+```markdown
+### Basic usage of the Button element
+```
+
+**example.css**
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  column-gap: 16px;
+  row-gap: 16px;
+}
+```
+
+**example.html**
+
+```html
+<div id="sample-buttons" class="grid">
+  <sd-button primary>Primary button</sd-button>
+  <sd-button>Simple button</sd-button>
+  <sd-button primary>Disabled primary button</sd-button>
+  <sd-button>Disabled simple button</sd-button>
+</div>
+```
+
+**example.ts**
+
+```typescript
+import "@cas-smartdesign/button";
+import { Button } from "@cas-smartdesign/button";
+
+document.querySelectorAll("#sample-buttons sd-button").forEach((element) => {
+  const button = element as Button;
+  button.addEventListener("click", () =>
+    console.log(`Clicked on${button.disabled ? " disabled" : ""}${button.primary ? " primary" : ""} button!`),
+  );
+});
+```