@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.
• 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

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

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

### Basic usage of the Button element

example.css

.grid {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  column-gap: 16px;
  row-gap: 16px;
}

example.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

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!`),
  );
});