SPARK-48: Publish Stacks-Svelte

.changeset/cyan-teachers-hear.md

@@ -0,0 +1,5 @@
+---
+"@stackoverflow/stacks-svelte": minor
+---
+
+[SPARK- 48] - publish stacks svelte to npm

.github/workflows/workflow.yml

@@ -15,7 +15,7 @@ jobs:
     name: ${{ matrix.command_description }}
     uses: ./.github/workflows/test.yml
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         include:
         - command_description: Build
@@ -42,8 +42,12 @@ jobs:
           command: npm run test:visual:ci -w packages/stacks-classic -- --config ./visual-runner/stacks-classic-runner-config/web-test-runner.config.ci.mjs
           needs_lfs: true
           needs_playwright: false # we are using playwright docker image to run visual tests
+        - command_description: Unit Tests (stacks-svelte)
+          command: npm run test -w packages/stacks-svelte
+          needs_lfs: false
+          needs_playwright: true
     with:
       command: ${{ matrix.command }}
       command_description: ${{ matrix.command_description }}
       needs_playwright: ${{ matrix.needs_playwright }}
-      needs_lfs: ${{ matrix.needs_lfs }}
+      needs_lfs: ${{ matrix.needs_lfs }}

.gitignore

@@ -87,3 +87,11 @@ dist/
 # Editors #
 ###########
 /.idea
+
+# Stacks-Svelte
+################
+**/storybook-static
+.eslintcache
+*.tsbuildinfo
+.svelte-kit
+/packages/stacks-svelte/lib/

.prettierignore

@@ -1,6 +1,7 @@
 *.md
 .vscode/
 dist/
+**/.svelte-kit
 # TODO: prettier breaks less files containing namespaced mixins with whitespaces
 # BEFORE PRETTIER: #stacks-internals #responsify('.w25', { width: 25% !important; });
 # AFTER PRETTIER:  #stacks-internals #responsify('.w25', { width: 25% !important; });;

README.md

@@ -1,23 +1,20 @@
 # Stacks
 
-[![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url]
-
 Stacks is Stack Overflow’s design system. It includes the resources needed to create consistent, predictable interfaces and workflows that conform to Stack Overflow’s principles, design language, and best practices.
 
 Our documentation is built with Stacks itself, using its [immutable, atomic classes](http://johnpolacek.com/rethinking/) and components.
 
 The Stacks website documents:
 
-### Product
+## Product
 - Semantic and accessible component markup
 - Cross-browser compatible Less / CSS
 - An [icon library](https://github.com/StackExchange/Stacks-Icons)
+- Svelte implementation of our library
 
-### Email
+## Email
 - Email templates & components
 
-Stacks documentation can be found at https://stackoverflow.design/
-
 ## Table of contents
 
 - [Using Stacks](#using-stacks)
@@ -30,14 +27,14 @@ Stacks documentation can be found at https://stackoverflow.design/
 - [Contributing](#contributing)
 - [License](#license)
 
-## Using Stacks
+# Using Stacks
 Using Stacks is outlined in our [usage guidelines](https://stackoverflow.design/product/develop/using-stacks).
 
 ## Migrating from v1 to v2
 
 To migrate from Stacks v1 to v2, see our [migration guide](/MIGRATION_GUIDE.md).
 
-## Local Development
+# Local Development
 
 This repo follows a monolithic structure and contains multiple packages split into [npm workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces). These can be found under the [packages/](https://github.com/StackExchange/Stacks/tree/develop/packages) folder.
 
@@ -58,10 +55,14 @@ npm start
 ```
 This command will pull up the local dev server at http://localhost:8080. You can also view our [building guidelines](https://stackoverflow.design/product/develop/building).
 
-## Stacks Classic
+## Stacks Classic 
+
+[![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url]
 
 This workspace contains the css and js sources that define and power the Stacks design system.
 
+### Formatting
+
 Format the source code with prettier by running:
 ```sh
 npm run format -w packages/stacks-classic
@@ -143,7 +144,46 @@ Update the css snapshots via:
 npm run test:less:update -w packages/stacks-classic
 ```
 
-## Releasing a new version of Stacks Docs / Stacks Classic
+## Stacks Svelte
+
+This workspace contains a Svelte implementation of the Stacks Classic design system. Unlike the Stacks-Classic workspace which has its documentation defined in the separate Stacks-Docs workspace, this one defines its documentation site directly within its own workspace which can be reached via https://svelte.stackoverflow.design
+
+We use [storybook](https://storybook.js.org/) for local development. To start the storybook server run:
+
+```bash
+npm run storybook -w packages/stacks-svelte
+```
+
+The storybook server will reflect the changes you make to the components stories in real time.
+We use [this addon](https://storybook.js.org/addons/@storybook/addon-svelte-csf) to write stories directly in Svelte syntax. Stories need to have the `*.stories.svelte` extension to be picked up.
+
+### Formatting
+
+```bash
+npm run format -w packages/stacks-svelte
+```
+
+### Linting
+
+```bash
+npm run lint -w packages/stacks-svelte
+```
+
+### Testing
+
+Stacks Svelte uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context.
+
+```bash
+npm run test -w packages/stacks-svelte
+```
+
+or to run the tests in watch mode:
+
+```bash
+npm run test:watch -w packages/stacks-svelte
+```
+
+# Releasing a new version of Stacks Docs + Stacks Classic or Stacks Svelte
 This repo uses [Semantic Versioning](https://semver.org/) to distribute Stacks Classic and Stacks Docs via [npm](https://www.npmjs.com/package/@stackoverflow/stacks), and publishes [release notes on Github](https://github.com/StackExchange/Stacks/releases). 
 
 We use [changesets](https://github.com/changesets/changesets) to automatize the steps necessary to publish to NPM, create GH releases and a changelog.

adrs/stacks-svelte/0001-localization.md

@@ -0,0 +1,35 @@
+# Localization
+
+**Date:** 2024-01-04
+
+**Related PR:** [#46](https://github.com/StackEng/Stacks-Svelte/pull/46)
+
+## Issue
+
+As more complex components are landing into Stacks Svelte (e.g. Modal, TextInput, etc...) we need a strategy to localize the text contained in those components (e.g. Close Button Label in the Modal) rather than keeping it hardcoded.
+
+## Decision
+
+We decided to delegate localization and translation concerns to consumers of the library exposing optional props prefixed by `i18n`. The default value of these props will be the English translation (which we will always fallback to in case consumer don't specify the props).
+**No hardcoded text is allowed in any component under any circumnstances.**
+
+Example:
+
+```svelte
+<Modal id="modal-example" visible={true} i18nCloseButtonLabel="Chiudi">
+```
+
+## Rationale
+
+Using props and delegating localization concerns to the consumers of the library is the simplest approach we can take to ship components that can be correctly rendered in internationalized pages and apps.
+The picked approach will also make consumption of those components possible with different translation engines (e.g. moonspeak in Core, a potential new translation engine, etc...).
+The downside of the approach is that the API of the components could become a bit bloated with a proliferation of optional props dedicated to pass on localized text. It also create more work for consumers who need to curate and provide the translations.
+
+We have considered maintaining localization files for primary languages ourselves and provide the ability for consumers to register their own translations. This solution would be more complex and it will increase maintainance work on our small team therefore we decided to avoid it for now.
+
+We don't exclude providing a different way for consumer to localize Stacks Svelte components in the future as the community tools and best practices on this topic evolve. We also expect this ADR to evolve over time as our library grow (e.g. if/when we will introduce a date picker).
+
+## Further Reading
+
+- [Carbon Svelte Component Library using props for localization](https://github.com/carbon-design-system/carbon-components-svelte/issues/858)
+- [SvelteKit i18n brainstorming thread](https://github.com/sveltejs/kit/issues/553)