Feature/5 tsbuild config

.gitignore

@@ -6,6 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
+tsconfig.tsbuildinfo
 
 node_modules
 dist

.storybook/main.ts

@@ -10,8 +10,10 @@ const config: StorybookConfig = {
   docs: {
     autodocs: "tag",
   },
-  staticDirs: ['../public'],
+  // staticDirs: ['../public'],
   async viteFinal(config, { configType }) {
+    config.optimizeDeps || (config.optimizeDeps = {})
+
     // customize the Vite config here
     config.optimizeDeps.include = [
       ...(config.optimizeDeps?.include ?? []),

README.md

@@ -16,20 +16,18 @@ pnpm install
 ## Storybook
 
 ```bash
-pnpm run storybook
+npm start
 ```
 
-## Build
+## Test
 
 ```bash
-pnpm run build
+npm test
 ```
 
-## Publish
+## Technical Documentation
 
-- Ensure all packages requiring publication have their `version` field in `package.json` updated to reflect the next version to be published.
-- Ensure a successful `pnpm run build` completes after the version updates are made.
-- Run `pnpm -r publish --access public` from the root directory to publish all packages with updated versions.
+See [docs](./docs/).
 
 ## Credits
 

design-system/package.json

@@ -22,11 +22,11 @@
   "main": "./dist/index.umd.js",
   "module": "./dist/index.js",
   "scripts": {
-    "build": "vite build; tsc -p ./tsconfig.json"
+    "build": "vite build && tsc -p ./tsconfig.build.json"
   },
   "devDependencies": {
-    "tslib": "^2.3.1",
-    "typescript": "^4.5.5",
+    "tslib": "^2.6.2",
+    "typescript": "^5.2.2",
     "vite": "^4.4.9"
   },
   "dependencies": {

design-system/src/assessment-widget.stories.ts

@@ -1,5 +1,4 @@
 import { b64images } from '@neighbourhoods/design-system-styles';
-import { html } from 'lit';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import NHAssessmentWidget from './assessment-widget';
 

design-system/src/index.ts

@@ -1,14 +1,30 @@
+import NHAlert from './alert'
+import NHAssessmentWidget from './assessment-widget'
+import NHButtonGroup from './button-group'
+import NHButton from './button'
+import NHCard from './card'
+import NHCardList from './card-list'
+import NHDialog from './dialog'
+import NHMenu from './menu'
+import NHPageHeaderCard from './page-header-card'
+import NHPagination from './pagination'
+import NHSlide from './slide'
+import NHTabButton from './tab-button'
+
 export * from './ancestors/base'
-export * from './alert'
-export * from './assessment-widget'
-export * from './button-group'
-export * from './button'
-export * from './card'
-export * from './card-list'
-export * from './dialog'
-export * from './menu'
-export * from './page-header-card'
-export * from './pagination'
-export * from './slide'
-export * from './tab-button'
+
 export * from './profile'
+export {
+  NHAlert,
+  NHAssessmentWidget,
+  NHButtonGroup,
+  NHButton,
+  NHCard,
+  NHCardList,
+  NHDialog,
+  NHMenu,
+  NHPageHeaderCard,
+  NHPagination,
+  NHSlide,
+  NHTabButton,
+}

design-system/src/post/post-card.stories.ts

@@ -1,7 +1,6 @@
 import NHPostCard from "./post-card";
 import { html } from "lit";
 import type { Meta, StoryObj } from "@storybook/web-components";
-import { BasicWidget } from "../assessment-widget.stories";
 
 customElements.define('nh-post-card', NHPostCard)
 

design-system/src/profile/index.ts

@@ -1,2 +1,7 @@
-export * from './profile-card';
-export * from './profile-identicon';
+import NHProfileCard from './profile-card';
+import NHProfileIdenticon from './profile-identicon';
+
+export {
+  NHProfileCard,
+  NHProfileIdenticon,
+}

design-system/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.d.ts", "**/*.stories.*"]
+}

design-system/tsconfig.json

@@ -1,23 +1,11 @@
 {
+  "extends": "../tsconfig.base.json",
   "compilerOptions": {
-    "module": "es6",
-    "target": "es2016",
-    "lib": ["es2017", "dom", "dom.iterable"],
-    "declaration": true,
-    "emitDeclarationOnly": false,
-    "outDir": "./dist",
-    "sourceMap": true,
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true,
-    "experimentalDecorators": true,
-    "forceConsistentCasingInFileNames": true,
-    "useDefineForClassFields": false
+    "outDir": "./dist"
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.stories.ts"]
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.d.ts"],
+  "references": [
+    { "path": "../tsconfig.json" }
+  ]
 }

dev-util/package.json

@@ -22,15 +22,16 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "scripts": {
-    "build": "vite build; tsc -p ./tsconfig.json"
+    "build": "vite build && tsc -p ./tsconfig.build.json"
   },
   "devDependencies": {
-    "tslib": "^2.3.1",
-    "typescript": "^4.5.5",
+    "tslib": "^2.6.2",
+    "typescript": "^5.2.2",
     "vite": "^4.4.9"
   },
   "dependencies": {
     "@lit-labs/scoped-registry-mixin": "^1.0.1",
+    "@neighbourhoods/design-system-components": "workspace:*",
     "@neighbourhoods/design-system-styles": "^0.0.3",
     "@scoped-elements/shoelace": "^0.1.0",
     "lit": "^2.2.0"

dev-util/src/design-system-imports.stories.ts

@@ -0,0 +1,41 @@
+/**
+ * Tests to assert functionality for various import formats of
+ * the Design System Components.
+ *
+ * @package: Neighbourhoods Dev Util Components
+ * @since:   2023-09-04
+ */
+
+import { NHButton } from '@neighbourhoods/design-system-components'
+import NHButton_only from '@neighbourhoods/design-system-components/button'
+
+import { html } from 'lit'
+import type { Meta, StoryObj } from '@storybook/web-components'
+
+// registering the elements is enough to test the validity of their class definitions
+customElements.define('test-1', NHButton)
+try {
+  customElements.define('test-2', NHButton_only)
+} catch (e) {
+  // Multiple registration of the same class should be detected. Any other error is a real error.
+  if (!(e instanceof DOMException && e.message.indexOf("constructor has already been used") !== -1)) {
+    throw e
+  }
+}
+
+interface Void {}
+
+const meta: Meta<Void> = {
+  title: 'NHDevUtil/DesignSystemImports',
+  component: 'nh-assessment-widget',
+  render: () => html`
+    <p>[compiler-level test only] <test-1 /></p>
+  `
+};
+
+export default meta;
+
+type Story = StoryObj<Void>;
+export const Test: Story = {
+  args: {},
+};

dev-util/tsconfig.build.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "paths": {
+      "@neighbourhoods/design-system-components": [
+        "../design-system/dist/index"
+      ],
+      "@neighbourhoods/design-system-components/*": [
+        "../design-system/dist/*"
+      ]
+    },
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.d.ts", "**/*.stories.*"]
+}

dev-util/tsconfig.json

@@ -1,23 +1,11 @@
 {
+  "extends": "../tsconfig.base.json",
   "compilerOptions": {
-    "module": "es6",
-    "target": "es2016",
-    "lib": ["es2017", "dom", "dom.iterable"],
-    "declaration": true,
-    "emitDeclarationOnly": false,
-    "outDir": "./dist",
-    "sourceMap": true,
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true,
-    "experimentalDecorators": true,
-    "forceConsistentCasingInFileNames": true,
-    "useDefineForClassFields": false
+    "outDir": "./dist"
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.stories.ts"]
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.d.ts"],
+  "references": [
+    { "path": "../tsconfig.json" }
+  ]
 }

docs/README.md

@@ -0,0 +1,75 @@
+# Neighbourhoods Storybook repository developer documentation
+
+
+## Publishing to NPM and other package registries
+
+- Ensure all packages requiring publication have their `version` field in `package.json` updated to reflect the next 
+  version to be published. Ensure all changes are committed and pushed and that the working copy is not dirty.
+- Ensure a successful `pnpm run build` completes after the version updates are made.
+- Run `pnpm -r publish --access public` from the root directory to publish all packages with updated versions.
+- Tag the new version/s and push the `git push --tags` to our shared remote.
+
+
+
+
+## Developing locally within downstream projects
+
+If you are building an Neighbourhoods Applet or other UI application then you
+may find it useful to be able to live-edit code in the Storybook and have it
+linked to the target application in question.
+
+To set this up you can simply run the following from wherever you are consuming
+the associated Neighbourhoods UI module from NPM:
+
+```bash
+pnpm link /path/to/this/repo/design-system
+```
+
+(Substituting whichever subdirectory your ESModule's `package.json` file is located in.)
+
+
+
+
+## Understanding compilation targets and the build system
+
+This repository is a monorepo containing separate but interrelated packages used
+in Neighbourhoods user interface applications.
+
+At the top level of the workspace, the Storybook runner packages and scripts are
+managed. When run in this mode through various `storybook` commands there is a
+single project-wide `tsconfig.json` which manages build artifacts *in memory*
+via [Vite](https://vitejs.dev/).
+
+Within each UI module subdirectory (eg. `design-system`, `dev-util`) there are 
+also configurations used in managing this build and separate on-disk output.
+Managing these distinctions requires creative use of the `paths` field in
+TypeScript's configuration files.
+
+An example can be seen in the dependency between 
+`@neighbourhoods/dev-util-components` and `@neighbourhoods/design-system-components`.
+
+
+### Registering a new ESModule with the build system
+
+- In `pnpm-workspace.yaml` add the new ESModule directory to the list
+- In the repository-level `tsconfig.json`:
+    - Add additional entries under `paths`, mapping the new module name & exports to the associated *source* file paths.
+- In the new ESModule directory, add two new TypeScript config files which `extends` from the root-level `tsconfig.base.json`:
+    - Add a new `tsconfig.json` file which `references` the root `tsconfig.json`  
+      > This enables these modules to be picked up by the repository-level 
+        Storybook / Vite build process and compiled **for Storybook** 
+        (mostly during development).
+    - Add a new `tsconfig.build.json` referenced in an isolated `package.json` build script  
+      > This will compile the module **for external consumers**.  
+      > All `**/*.stories.*` files should be added to the `exclude` list to avoid including them in packaged modules on NPM.
+- In the new ESModule directory, copy a new `vite.config.js` and setup a `build` script in `package.json` as
+  `vite build && tsc -p ./tsconfig.build.json`.
+
+
+### Configuring cross-module dependencies
+
+- In the dependant (consuming) ESModule directory:
+    - Add a reference to the dependency (providing) ESModule using PNPM's `workspace:*` syntax.
+    - Add additional entries under `paths`, mapping the new module name & exports to the associated *built* (not source) 
+      file paths (as determined by the dependency (providing) ESModule)
+        - Ensure any dependency ordering is reflected in the top-level `package.json`'s `build` script.