fluent-svelte-extra 1.0.0

package/src/routes/docs/components/slider.md

@@ -0,0 +1,165 @@
+<script lang="ts">
+    import { Slider, Button, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/Slider/Slider.svelte?sveld&raw";
+</script>
+
+A slider is a control that lets the user select from a range of values by moving a thumb control along a track.
+
+```ts
+import { Slider } from "fluent-svelte";
+```
+
+<Showcase columns={4} columnWidth="120px" repl="461bd056ac7b4c7a920354256560b0a4">
+    <div style="display: contents" on:mousedown|stopPropagation>
+        <Slider />
+        <Slider value={10000} step={10000} max={30000} ticks={[10000, 20000]} suffix="cm" />
+        <Slider value={80} max={200} reverse />
+        <Slider value={50} disabled />
+        <div style="block-size: 72px;">
+            <Slider orientation="vertical" value={24} />
+        </div>
+        <Slider orientation="vertical" value={50} reverse />
+        <Slider orientation="vertical" value={76} track={false} ticks={[24, 50, 76]} tickPlacement="after" />
+        <Slider orientation="vertical" value={24} disabled />
+    </div>
+</Showcase>
+
+## Usage
+
+### Controlling Value
+
+By default, sliders are created with a value of `0`. This starts the slider thumb at 0% of the track. You can set the initial value of the slider by setting the `value` property.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider value={20} />
+```
+
+Additionally, you can use svelte's two-way binding syntax to bind the value to a variable.
+
+```svelte example
+<script>
+	import { Slider } from "fluent-svelte";
+
+	let value = 0;
+</script>
+
+<Slider bind:value />
+
+Current value: {value}
+```
+
+### Minimum and Maximum Values
+
+Sliders can normally only take in `value`s ranging from `0` to `100`. This can be changed by setting the `min` and `max` properties.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider min={100} max={500} value={250} />
+```
+
+### Step
+
+A `step` property can be set to control the granularity of the slider. For example, if you set the `step` to `10`, the slider will only allow values that are multiples of `10`. The default step of `1` means that the slider can take any whole-number value.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider step={10} />
+```
+
+### Using Ticks
+
+Slider ticks are small markers along the slider rail that mark a significant value. Ticks are purely visual, and do not alter user interaction. You can add slider ticks by passing an array of numbers within the slider's value range into the `ticks` property:
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider ticks={[0, 50, 100]} />
+```
+
+You can also customize the appearance of the slider's ticks. The `tickPlacement` property will control how the ticks are displayed on the slider rail. The default value is `around`, which shows the ticks at both sides of the rail vertically. Tick placement can be either `around`, `before`, or `after`.
+
+### Tooltips
+
+All sliders are accompanied by a tooltip that displays the current value of the slider. If you do not wish to display a tooltip, you can set the `tooltip` property to `false`.
+
+```svelte hideScript
+<Slider tooltip={false} />
+```
+
+Tooltip text can also be customized through the `prefix` and `suffix` properties, which will add a string respectively before or after the tooltip's text. This is useful if you want to convey units of measurement or other information about the slider's value.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider prefix="$" />
+<Slider suffix=" meters" />
+```
+
+If you require further tooltip configuration, the tooltip's content can also be entirely overrided with your own using the `tooltip` slot.
+
+The `tooltip` slot has three slot props: `value`, `prefix` and `suffix` which grant you access to the current value and the prefix/suffix strings respectively.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider>
+	<svelte:fragment slot="tooltip" let:value let:prefix let:suffix>
+		{prefix}{value}{suffix}
+		<marquee>Custom HTML content!</marquee>
+	</svelte:fragment>
+</Slider>
+```
+
+### Direction and Orientation
+
+Sliders can be displayed in either a horizontal (left and right) or vertical orientation (up and down). By default, sliders are displayed in a horizontal orientation. You can change this by setting the `orientation` property to `vertical`.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<div style="block-size: 120px;">
+	<Slider orientation="vertical" />
+</div>
+```
+
+Slider tracks can also be reversed using the `reverse` property. This will change the direction of the slider's track. For example, if the slider is horizontal and the `reverse` property is set to `true`, the track will be displayed from right to left.
+
+```svelte example hideScript
+<script>
+	import { Slider } from "fluent-svelte";
+</script>
+
+<Slider reverse />
+```
+
+### Trackless Sliders
+
+A slider's fill indication can be removed by setting the `track` property to `false`. This will only hide the _track_, not the rail or thumb.
+
+### Disabled Sliders
+
+If the slider is not meant to be clicked, you can use the `disabled` property to visually indicate this. If a slider is disabled, it will be unclickable.
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/textblock.md

@@ -0,0 +1,46 @@
+<script lang="ts">
+    import { TextBlock } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/TextBlock/TextBlock.svelte?sveld&raw";
+</script>
+
+The TextBlock control renders a block of text in a given style depending on it's indended purpose in the layout. As the visual representation of language, TextBlock’s main task is to communicate information. Its style should never get in the way of that goal.
+
+```ts
+import { TextBlock } from "fluent-svelte";
+```
+
+<Showcase repl="9354fe2253804088b23e4dc9a882fa24" columns={3}>
+    <TextBlock variant="caption">Caption</TextBlock>
+    <TextBlock variant="body">Body</TextBlock>
+    <TextBlock variant="bodyStrong">Body Strong</TextBlock>
+    <TextBlock variant="bodyLarge">Body Large</TextBlock>
+    <TextBlock variant="subtitle">Subtitle</TextBlock>
+    <TextBlock variant="title">Title</TextBlock>
+    <TextBlock variant="titleLarge">Title Large</TextBlock>
+    <TextBlock variant="display">Display</TextBlock>
+</Showcase>
+
+## Usage
+
+TextBlocks only render a single given element, depending on which style is specified.
+
+### Styles
+
+TextBlocks can be customized to a given purpose by passing in a `variant` property. The default variant is `body`.
+
+| Variant      | HTML Tag | Weight | Primary Font Family       | Size / Line Height | Preview                                          |
+| ------------ | -------- | ------ | ------------------------- | ------------------ | ------------------------------------------------ |
+| `caption`    | `<span>` | `400`  | Segoe UI Variable Small   | 12/16px            | <TextBlock variant="caption">Text</TextBlock>    |
+| `body`       | `<span>` | `400`  | Segoe UI Variable Text    | 14/20px            | <TextBlock variant="body">Text</TextBlock>       |
+| `bodyStrong` | `<h6>`   | `600`  | Segoe UI Variable Text    | 14/20px            | <TextBlock variant="bodyStrong">Text</TextBlock> |
+| `bodyLarge`  | `<h5>`   | `600`  | Segoe UI Variable Text    | 18/24px            | <TextBlock variant="bodyLarge">Text</TextBlock>  |
+| `subtitle`   | `<h4>`   | `600`  | Segoe UI Variable Display | 20/28px            | <TextBlock variant="subtitle">Text</TextBlock>   |
+| `title`      | `<h3>`   | `600`  | Segoe UI Variable Display | 28/36px            | <TextBlock variant="title">Text</TextBlock>      |
+| `titleLarge` | `<h2>`   | `600`  | Segoe UI Variable Display | 40/52px            | <TextBlock variant="titleLarge">Text</TextBlock> |
+| `display`    | `<h1>`   | `600`  | Segoe UI Variable Display | 68/92px            | <TextBlock variant="display">Text</TextBlock>    |
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/textbox.md

@@ -0,0 +1,124 @@
+<script lang="ts">
+    import { TextBox, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/TextBox/TextBox.svelte?sveld&raw";
+</script>
+
+The TextBox control lets a user type text into an app. The text displays on the screen in a simple, plaintext format on a single line. It additionally comes with a set of buttons which allow users to perform specialized actions on the text, such as showing a password or clearing the TextBox's contents.
+
+```ts
+import { TextBox } from "fluent-svelte";
+```
+
+<Showcase columns={2} repl="65b817e67ff3450da0c5755b5fdac9f7">
+    <TextBox placeholder="TextBox" />
+    <TextBox placeholder="TextBox" disabled />
+    <TextBox type="search" placeholder="TextBox" />
+    <TextBox type="search" placeholder="TextBox" disabled />
+    <TextBox type="password" placeholder="TextBox" />
+    <TextBox type="password" placeholder="TextBox" disabled />
+</Showcase>
+
+## Usage
+
+TextBox is an extension of [HTML's native `<input />` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). Most props/attributes that aren't explicitly documented here should still work the same.
+
+### Controlling Value
+
+A TextBox's current text content can be set with the `value` property.
+
+```svelte hideScript
+<TextBox value="Default value" />
+```
+
+Additionally, you can use svelte's two-way binding syntax to bind the value to a variable.
+
+```svelte example
+<script>
+	import { TextBox } from "fluent-svelte";
+
+	let value = "Default value";
+</script>
+
+<TextBox bind:value />
+
+Current value: {value}
+```
+
+### TextBox Types
+
+You can customize the intended input type of the TextBox by setting the `type` property. Most HTML [`<input>` type attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types) that accept text input are supported.
+
+Supported types: `text`, `number`, `search`, `password`, `email`, `tel`, `url`, `date`, `datetime-local`, `month`, `time`, `week`.
+
+<InfoBar severity="caution" title="NumberBox vs. the {`"number"`} type">
+While you <i>can</i> use the <code>number</code> type with TextBox, it's probably a better idea to use the specialized <a href="numberbox">NumberBox</a> component instead, which is an extension of TextBox designed for handling numeric inputs.
+</InfoBar>
+
+Most of these types will simply set the `type` attribute of the TextBox's input element. Some of these types, however, have additional functionality added specific to their input method.
+
+-   On `search` types - A search button will be added to the end of the TextBox to allow users to submit a search query. You can use the `on:search` event to handle the search query. If you wish to hide the search button when using this type, you can set the `searchButton` property to `false`.
+-   On `password` types - A password reveal button will be added to the end of the TextBox to allow users to reveal the input's value. You can use the `on:reveal` event to run code when the password is revealed. If you wish to hide the reveal button when using this type, you can set the `revealButton` property to `false`.
+
+### Placeholders
+
+TextBox supports a `placeholder` property that will be displayed as text in lower emphasis when it's value is empty. These can be used to describe the purpose or type of value the TextBox is meant to accept.
+
+```svelte example hideScript
+<script>
+	import { TextBox } from "fluent-svelte";
+</script>
+
+<TextBox placeholder="Send a message" />
+```
+
+### Buttons
+
+TextBox supports a set of buttons that are added to the end of it's container. These buttons can be used to perform actions on the TextBox's value. [Depending on the `type` of the TextBox, these buttons may vary with different functionality and behavior](#textbox-types).
+
+Most TextBox types will feature a clear button. This button will clear the TextBox's value, then focus the input when clicked. If you wish to hide this button, you can set the `clearButton` property to `false`. If you wish to run any code after the clear button is used, you can also handle the `on:clear` event.
+
+Along with the builtin action buttons, you can also add your own buttons to the end of the TextBox using the `TextBoxButton` component and the TextBox's `buttons` slot:
+
+```svelte example hideScript
+<script>
+	import { TextBox, TextBoxButton } from "fluent-svelte";
+</script>
+
+<TextBox placeholder="Custom buttons!">
+	<TextBoxButton slot="buttons" on:click={() => alert("Clicked!")}>
+		<!-- https://github.com/microsoft/fluentui-system-icons -->
+		<svg width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+			<path
+				d="M7.85355 0.146447C7.65829 -0.0488155 7.34171 -0.0488155 7.14645 0.146447C6.95118 0.341709 6.95118 0.658291 7.14645 0.853553L8.29603 2.00314C4.80056 2.11088 2 4.97839 2 8.5C2 12.0899 4.91015 15 8.5 15C12.0899 15 15 12.0899 15 8.5C15 8.48656 15 8.47313 14.9999 8.45971C14.9983 8.2001 14.7805 8 14.5209 8H14.4782C14.2093 8 14 8.23107 14 8.5C14 11.5376 11.5376 14 8.5 14C5.46243 14 3 11.5376 3 8.5C3 5.53311 5.34917 3.11491 8.28892 3.00398L7.14645 4.14645C6.95118 4.34171 6.95118 4.65829 7.14645 4.85355C7.34171 5.04882 7.65829 5.04882 7.85355 4.85355L9.85355 2.85355C10.0488 2.65829 10.0488 2.34171 9.85355 2.14645L7.85355 0.146447ZM11.8536 6.14645C12.0488 6.34171 12.0488 6.65829 11.8536 6.85355L8.85355 9.85355C8.65829 10.0488 8.34171 10.0488 8.14645 9.85355L6.64645 8.35355C6.45118 8.15829 6.45118 7.84171 6.64645 7.64645C6.84171 7.45118 7.15829 7.45118 7.35355 7.64645L8.5 8.79289L11.1464 6.14645C11.3417 5.95118 11.6583 5.95118 11.8536 6.14645Z"
+				fill="currentColor"
+			/>
+		</svg>
+	</TextBoxButton>
+</TextBox>
+```
+
+### Disabled and Readonly States
+
+There are two methods to (completely) restrict manual input on a TextBox: the `disabled` and `readonly` properties.
+
+-   The `disabled` property will prevent the user from entering text into the TextBox as well as style the TextBox to indicate this. The TextBox will not be focusable and will not respond to keyboard events.
+-   The `readonly` property will only prevent the user from entering text into the TextBox. The TextBox will still be focusable, however, and no changes to the styling will be made.
+
+<InfoBar severity="attention" title="Buttons and these properties">
+    It should be noted that while using either of these modes that the clear button will not be displayed, in order to prevent users from modifying the TextBox's content. The <code>clearButton</code> property will have no effect on this behavior. Additionally, when the TextBox is <code>disabled</code>, the search and password reveal buttons will not be rendered into their respective types either.
+</InfoBar>
+
+```svelte example hideScript
+<script>
+	import { TextBox } from "fluent-svelte";
+</script>
+
+<TextBox placeholder="disabled TextBox" disabled />
+<TextBox placeholder="readonly TextBox" readonly />
+```
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/toggleswitch.md

@@ -0,0 +1,73 @@
+<script lang="ts">
+    import { ToggleSwitch, Button, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/ToggleSwitch/ToggleSwitch.svelte?sveld&raw";
+</script>
+
+The toggle switch represents a physical switch that allows users to turn things on or off, like a light switch. Use toggle switch controls to present users with two mutually exclusive options (such as on/off), where choosing an option provides immediate results.
+
+```ts
+import { ToggleSwitch } from "fluent-svelte";
+```
+
+<Showcase columns={2} repl="4b7217ee24294302937ec6c69db1bbc0">
+    <ToggleSwitch>ToggleSwitch</ToggleSwitch>
+    <ToggleSwitch checked>ToggleSwitch</ToggleSwitch>
+    <ToggleSwitch disabled>ToggleSwitch</ToggleSwitch>
+    <ToggleSwitch checked disabled>ToggleSwitch</ToggleSwitch>
+</Showcase>
+
+## Usage
+
+`<ToggleSwitch />` is a wrapper around HTML's `<input />` checkbox type. As such, the APIs share some similarities.
+
+### Checking and Unchecking
+
+You can programmatically control if the ToggleSwitch is in it's checked state by setting the `checked` property.
+
+```svelte example hideScript
+<script>
+	import { ToggleSwitch } from "fluent-svelte";
+</script>
+
+<ToggleSwitch checked />
+```
+
+Additionally, you can use svelte's two-way binding syntax to bind the checked state to a variable.
+
+```svelte example
+<script>
+	import { ToggleSwitch } from "fluent-svelte";
+
+	let checked = false;
+</script>
+
+<ToggleSwitch bind:checked />
+
+Current state: {checked ? "checked" : "unchecked"}
+```
+
+### Labels
+
+Passing in content to the ToggleSwitch's slot will cause that content to be rendered into a label for the control.
+
+```svelte example hideScript
+<script>
+	import { ToggleSwitch } from "fluent-svelte";
+</script>
+
+<ToggleSwitch>I have a label!</ToggleSwitch>
+```
+
+### Value
+
+For usage in forms, you can set a `value` property which will set the [value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value) of the ToggleSwitch's `<input>` element.
+
+### Disabled ToggleSwitches
+
+If the ToggleSwitch is not meant to be clicked, you can use the `disabled` property to visually indicate this. If a ToggleSwitch is disabled, it will be unclickable.
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/getting-started.md

@@ -0,0 +1,116 @@
+<script lang="ts">
+    import { InfoBar, Button } from "$lib";
+    import { CopyBox } from "$site/lib";
+</script>
+
+This page will guide you through the process of adding fluent-svelte to your existing Svelte project. If you don't have a Svelte or SvelteKit project already, you can create one using [this guide](https://svelte.dev/blog/the-easiest-way-to-get-started).
+
+<InfoBar severity="attention" title="Before We Start" message="This tutorial assumes you have basic knowledge of Svelte.">
+    <Button slot="action" variant="accent">
+        Learn Svelte
+    </Button>
+</InfoBar>
+
+### Step 1: Install the Library
+
+This will install fluent-svelte and it's required dependencies. This can be done using a package manager of your choice.
+
+<label>
+    npm
+    <CopyBox value="npm i --save-dev fluent-svelte" />
+</label>
+
+<label>
+    pnpm
+    <CopyBox value="pnpm i --save-dev fluent-svelte" />
+</label>
+
+<label>
+    yarn
+    <CopyBox value="yarn add --dev fluent-svelte" />
+</label>
+
+### Step 2: Add Theme File
+
+Fluent Svelte components use a set of common resources to style their elements. These values are defined in a theme file that must be imported into your project before components can render properly.
+
+`src/App.svelte` (or `src/routes/__layout.svelte` if using SvelteKit)
+
+```svelte
+<script>
+	import "fluent-svelte/theme.css";
+</script>
+```
+
+<InfoBar title="Bundler Support" severity="caution">
+    In some cases, your bundler may not have the capability to resolve CSS files. Both the default Svelte template and the SvelteKit starter project (Vite) have this ability, however you might need to install a <a href="https://gist.github.com/Tropix126/6306afeffbcc551425d5658b856e8c4c" target="_blank" rel="noreferrer noopener">dedicated bundler plugin</a> to import CSS.
+</InfoBar>
+
+Alternatively, you can import the theme file from a CDN (though this generally isn't recommended).
+
+```svelte
+<style>
+	@import url("https://unpkg.com/fluent-svelte/theme.css");
+	/* ...or @import url("https://cdn.jsdelivr.net/npm/fluent-svelte/theme.css"); */
+</style>
+```
+
+### Step 3: Importing a Component
+
+Components are exported from a single index file in the library. They can be imported and used in your project like so:
+
+```svelte example
+<script>
+	import { Button, Checkbox } from "fluent-svelte";
+</script>
+
+<Button>Click me!</Button>
+<Checkbox>Check me!</Checkbox>
+```
+
+Alternatively you can import under a namespace:
+
+```svelte
+<script>
+	import * as Fluent from "fluent-svelte";
+</script>
+
+<Fluent.Button>Click me!</Fluent.Button>
+<Fluent.Checkbox>Check me!</Fluent.Checkbox>
+```
+
+### Svelte REPL Usage
+
+`fluent-svelte` components can also be imported into the [Svelte REPL](https://svelte.dev/repl/).
+
+In the REPL, packages are automatically installed by name when using an `import` statement, so the installation step can be skipped. Because the REPL doesn't support importing CSS in `node_modules`, we'll need to import the theme file through a CDN.
+
+```svelte
+<script>
+	import { Button, Checkbox } from "fluent-svelte";
+</script>
+
+<button>Click me!</button>
+
+<style>
+	@import url("https://unpkg.com/fluent-svelte/theme.css");
+
+	/* Some base styles to get things looking right. */
+	:global(body) {
+		background-color: var(--fds-solid-background-base);
+		color: var(--fds-text-primary);
+	}
+</style>
+```
+
+<Button variant="hyperlink" href="https://svelte.dev/repl/2a30b6d202d24fb6b14783132b86b706" target="_blank" rel="noreferrer noopener">View this in the REPL</Button>
+
+<style>
+    h3 {
+        margin-block-start: 72px !important;
+    }
+
+    label {
+        font-weight: 600;
+    }
+</style>

package/src/routes/docs/index.md

@@ -0,0 +1,37 @@
+<script>
+    import { InfoBar } from "$lib";
+</script>
+
+Welcome to the Fluent Svelte documentation! This page will explain the basic concepts and usage of the library.
+
+### What is this?
+
+`fluent-svelte` is a [Svelte](http://svelte.dev/) component UI library that emulates the look and feel of [Microsoft's Windows UI Controls](https://github.com/microsoft/microsoft-ui-xaml/) which conform to the Fluent Design System.
+
+<InfoBar
+    severity="caution"
+    title="Before We Begin"
+    message="This is not a 1-to-1 re-implementation of WinUI, but rather a faithful attempt to emulate the look and feel of WinUI on the web. Some controls will have API or behaviorial differences, but the overall look and feel should be very similar."
+/>
+
+### Features
+
+-   [SvelteKit](https://kit.svelte.dev/) and SSR Compatible
+-   [TypeScript](https://typescriptlang.org/) and type definitions are supported, but optional.
+-   Full RTL support with no additional configuration.
+-   All components are accessible according to [WAI-ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) standards.
+-   Theming support using CSS custom properties.
+-   Minimal third-party dependency usage.
+-   Reduced motion support.
+-   Easy setup. Just install the library, add some base styles, and you're ready to go.
+-   Minimal CSS overhead. Styles are included and scoped alongside their respective components, only bundling the CSS you need.
+
+### Undocumented Components
+
+This documentation site is still not entirely finished. Many components exported in the library are not yet documented. That progress can be tracked [here](https://github.com/Tropix126/fluent-svelte/issues/13). For now, i've setup a testing page with every component included in the library that is viewable [here](https://fluent-svelte.vercel.app/test). It's source can be viewed [here](https://github.com/Tropix126/fluent-svelte/blob/main/src/routes/test/index.svelte).
+
+Please keep in mind that any undocumented component is _considered to be in the 0.x phase of development_. This means that they could potentially recieve breaking API changes or be heavily updated before being finalized.
+
+### Changelog
+
+See [CHANGELOG.md](https://github.com/Tropix126/fluent-svelte/blob/main/CHANGELOG.md).