@axel669/zephyr 0.2.0-beta.3 → 0.3.6

package/src/composed/data-table.md

@@ -1,85 +1,86 @@
-NOTE: include Th as its own component
-
-# DataTable
-
-The DataTable is a more advanced way to show data on screen. Underneath is
-a table element like the Table component, but the DataTable supports
-more fine-grained control over how data is passed, how rows are displayed,
-and pagination.
-
-> If pagination is not needed, the DataTable may not be necessary as it will
-> only be shortcutting data formatting at that point.
-
-## Props
-All [windstorm functions](https://axel669.github.io/lib.windstorm/#css-shorthands)
-are supported.
-
-- ### color
-    Sets `$color`
-
-### cols
-`Array`
-
-    The columns that should be displayed. Should be in the format of
-    `{ label, width?, format?, prop? }`. If a format function is provided,
-    it is called on each cell to determine a cells value as
-    `format(rowItem)`, otherwise the property defined in prop will be used
-    as the cell value.
-
-### data
-`Array`
-
-    The data to display. Each item in the array can be in either the same
-    format as the Table, or any kind of object if column format functions
-    are used.
-
-### cellWSX
-`function`
-
-    If given, this function will be called for each cell, and should return
-    an object that will be passed to the `wsx` action for each <td>
-    generated. The function is passed `(rowvalue, rowNum, col)`.
-
-### rowWSX
-`function`
-
-    If given, this function will be called for each row, and should return
-    an object that will be passed to the `wsx` action for each <tr>
-    generated. The function is passed `(rowValue, rowNum)`.
-- ### page
-    The current page of data being viewed. Can be bound, or set to control
-    which page is displayed
-- ### pageSize
-    The number of items to show on each page. Default is 10
-- ### rowHeight
-    The height of each row. Can be set individually through rowWSX, but
-    that may lead to a degraded user experience if the rows change size
-    while paging through the data
-
-## Example
-```js
-let page
-const cols = [
-    { label: "N", prop: "a" },
-    { label: "Squared", prop: "b" },
-    { label: "Cubed", format: row => `^3 = ${row.c}` },
-]
-const data = [
-    { a: 1, b: 1 ** 2, c: 1 ** 3 },
-    { a: 2, b: 2 ** 2, c: 2 ** 3 },
-    { a: 3, b: 3 ** 2, c: 3 ** 3 },
-    { a: 4, b: 4 ** 2, c: 4 ** 3 },
-    { a: 5, b: 5 ** 2, c: 5 ** 3 },
-    { a: 6, b: 6 ** 2, c: 6 ** 3 },
-    { a: 7, b: 7 ** 2, c: 7 ** 3 },
-    { a: 8, b: 8 ** 2, c: 8 ** 3 },
-    { a: 9, b: 9 ** 2, c: 9 ** 3 },
-    { a: 10, b: 10 ** 2, c: 10 ** 3 },
-    { a: 11, b: 11 ** 2, c: 11 ** 3 },
-    { a: 12, b: 12 ** 2, c: 12 ** 3 },
-    { a: 13, b: 13 ** 2, c: 13 ** 3 },
-]
-```
-```svelte
-<DataTable {cols} {data} color="warning" pageSize={3} bind:page />
-```
+# DataTable
+
+The DataTable is a more advanced way to show data on screen. Underneath is
+a [Table](../data-display/table.md) component, but with additional functionality
+for pagination, sorting, and fitering.
+
+> If pagination is not needed, the DataTable may not be necessary as it will
+> only be shortcutting data formatting at that point.
+
+## Props
+
+### color
+Sets `$color`
+
+### data
+`Array`
+
+The data to display. Each item in the array can be in either the same
+format as the Table, or any kind of object if column format functions
+are used.
+
+### page
+`Number`
+
+The current page of data being viewed. Can be bound, or set to control
+which page is displayed
+
+### pageSize
+`Number`
+
+The number of items to show on each page. Default is 10.
+
+### rowHeight
+The height of each row. The component uses this to make empty rows the same
+height as rows with data so that the pagination doesnt randomly resize the
+visual area of the table.
+
+## Slots
+
+### header
+A fragment that should contain the header cells for the table header. A standard
+`th` can be used, but the [TH](./data-table/th.md) element from zephyr has
+additional configuration to handle more complex header-related actions.
+
+### row
+A fragment that should use regular `td` elements to define how a row should be
+layed out. The fragment will need `let:row` to access each row's data for
+displaying it.
+
+## Example
+```svelte
+<script>
+    import { DataTable, TH, sorts } from "@axel669/zephyr"
+
+    let page
+    const data = [
+        { a: 1, b: 1 ** 2, c: 1 ** 3 },
+        { a: 2, b: 2 ** 2, c: 2 ** 3 },
+        { a: 3, b: 3 ** 2, c: 3 ** 3 },
+        { a: 4, b: 4 ** 2, c: 4 ** 3 },
+        { a: 5, b: 5 ** 2, c: 5 ** 3 },
+        { a: 6, b: 6 ** 2, c: 6 ** 3 },
+        { a: 7, b: 7 ** 2, c: 7 ** 3 },
+        { a: 8, b: 8 ** 2, c: 8 ** 3 },
+        { a: 9, b: 9 ** 2, c: 9 ** 3 },
+        { a: 10, b: 10 ** 2, c: 10 ** 3 },
+        { a: 11, b: 11 ** 2, c: 11 ** 3 },
+        { a: 12, b: 12 ** 2, c: 12 ** 3 },
+        { a: 13, b: 13 ** 2, c: 13 ** 3 },
+    ]
+</script>
+
+<DataTable {cols} {data} color="warning" pageSize={3} bind:page>
+    <svelte:fragment slot="header">
+        <TH sort={sorts.natural}>N</TH>
+        <th>Squared</th>
+        <th>Cubed</th>
+    </svelte:fragment>
+
+    <svelte:fragment slot="row" let:row>
+        <td>{row.a}</td>
+        <td>{row.b}</td>
+        <td>^3 = {row.c}</td>
+    </svelte:fragment>
+</DataTable>
+```

package/src/composed/data-table.svelte

@@ -1,149 +1,199 @@
-<svelte:options immutable />
-
-<script context="module">
-    // find the first filter in the list that returns false
-    const applyFilters = (data, filters) => {
-        if (Array.isArray(data) === false) {
-            return null
-        }
-        return data.filter(
-            (row) => {
-                for (const [filter, value] of filters) {
-                    if (filter(row, value) === false) {
-                        return false
-                    }
-                }
-                return true
-            }
-        )
-    }
-    const sliceData = (data, page, pageSize, sortFunc) => {
-        if (data === null) {
-            return []
-        }
-        const sorted = data.sort(sortFunc)
-        return Array.from(
-            { length: pageSize },
-            (_, i) => sorted[page * pageSize + i]
-        )
-    }
-    const noSort = {
-        direction: null,
-        func: (a, b) => 0,
-        base: null,
-    }
-
-    export const dtContext = Symbol("table key")
-</script>
-
-<script>
-    import { createEventDispatcher, setContext } from "svelte"
-    import { writable } from "svelte/store"
-
-    import Button from "../control/button.svelte"
-    import Icon from "../info/icon.svelte"
-    import Paper from "../layout/paper.svelte"
-    import Table from "../data-display/table.svelte"
-    import Text from "../text.svelte"
-
-    import Grid from "../layout/grid.svelte"
-
-    import wsx from "../wsx.mjs"
-    import { handler$, eventHandler$ } from "../handler$.mjs"
-
-    export let color = false
-    export let fillHeader = true
-    export let data
-    export let pageSize = 10
-    export let page = 0
-    export let rowHeight = "40px"
-
-    let sorting = noSort
-    let filters = new Map()
-    let filterFunctions = []
-
-    $: filteredData = applyFilters(data, filterFunctions)
-    $: rows = sliceData(filteredData, page, pageSize, sorting.func)
-    $: rowCount = filteredData?.length ?? 0
-    $: pageCount = Math.ceil(rowCount / pageSize)
-    $: maxPage = Math.max(pageCount - 1, 0)
-
-    $: if (filteredData === null) {
-        console.warn("DataTable: data is not an array")
-    }
-
-    const prev = () => page = Math.max(0, page - 1)
-    const next = () => page = Math.min(maxPage, page + 1)
-
-    const updateSort = (func) => {
-        if (sorting.base === func) {
-            if (sorting.direction === "desc") {
-                sorting = noSort
-                return
-            }
-            sorting = {
-                func: (a, b) => -func(a, b),
-                base: func,
-                direction: "desc"
-            }
-            return
-        }
-        sorting = {
-            func,
-            base: func,
-            direction: "asc",
-        }
-    }
-    const updateFilter = (func, value) => {
-        if (func === null) {
-            return
-        }
-        filters.set(func, value)
-        filterFunctions = [
-            ...filters.entries()
-        ]
-    }
-
-    const context = writable({})
-    $: $context = {
-        updateSort,
-        fillHeader,
-        sorting,
-        updateFilter,
-    }
-    setContext(dtContext, context)
-
-    const fire = createEventDispatcher()
-    const pass = handler$(
-        (row) => fire("row-click", row)
-    )
-</script>
-
-<Paper card {color} l-fl.cross="stretch" l-p="0px">
-    <Table data={rows} {color} {fillHeader} {...$$restProps}>
-        <tr ws-x="h.min[{rowHeight}]" slot="header">
-            <slot name="header">
-                <th>No Header Defined</th>
-            </slot>
-        </tr>
-        <tr ws-x="h[{rowHeight}]" slot="row" let:row>
-            <slot name="row" {row}>
-                <th>No Row Defined</th>
-            </slot>
-        </tr>
-        <tr ws-x="h[{rowHeight}]" slot="empty-row" />
-    </Table>
-    <Grid slot="footer" gr.cols="min-content min-content min-content 1fr">
-        {#if pageCount > 0}
-            <Button on:click={prev} disabled={page === 0}>
-                <Icon name="arrow-big-left" />
-            </Button>
-            <Button on:click={next} disabled={page === maxPage}>
-                <Icon name="arrow-big-right" />
-            </Button>
-            <Text adorn t.ws="nowrap">
-                Page {page + 1} / {pageCount}
-            </Text>
-        {/if}
-    </Grid>
-</Paper>
+<svelte:options immutable />
+
+<script context="module">
+    // find the first filter in the list that returns false
+    const applyFilters = (data, filters) => {
+        if (Array.isArray(data) === false) {
+            return null
+        }
+        return data.filter(
+            (row) => {
+                for (const [filter, value] of filters) {
+                    if (filter(row, value) === false) {
+                        return false
+                    }
+                }
+                return true
+            }
+        )
+    }
+    const sliceData = (data, page, pageSize, sortFunc) => {
+        if (data === null) {
+            return []
+        }
+        const sorted = data.sort(sortFunc)
+        return Array.from(
+            { length: pageSize },
+            (_, i) => sorted[page * pageSize + i]
+        )
+    }
+    const noSort = {
+        direction: null,
+        func: (a, b) => 0,
+        base: null,
+    }
+
+    export const dtContext = Symbol("table key")
+</script>
+
+<script>
+    import { createEventDispatcher, setContext } from "svelte"
+    import { writable } from "svelte/store"
+
+    import Button from "../control/button.svelte"
+    import Icon from "../info/icon.svelte"
+    import Paper from "../layout/paper.svelte"
+    import Table from "../data-display/table.svelte"
+    import Text from "../text.svelte"
+
+    import Grid from "../layout/grid.svelte"
+
+    import wsx from "../wsx.mjs"
+    import { handler$, eventHandler$ } from "../handler$.mjs"
+
+    export let color = false
+    export let fillHeader = true
+    export let data
+    export let pageSize = 10
+    export let page = 0
+    export let rowHeight = "40px"
+    export let scrollable = false
+    export let height = null
+
+    let sorting = noSort
+    let filters = new Map()
+    let filterFunctions = []
+    let jumpTarget = "1"
+
+    $: filteredData = applyFilters(data, filterFunctions)
+    $: rows = sliceData(filteredData, page, pageSize, sorting.func)
+    $: rowCount = filteredData?.length ?? 0
+    $: pageCount = Math.ceil(rowCount / pageSize)
+    $: maxPage = Math.max(pageCount - 1, 0)
+    $: jumpTarget = (page + 1).toString()
+
+    $: if (filteredData === null) {
+        console.warn("DataTable: data is not an array")
+    }
+
+    const prev = () => page = Math.max(0, page - 1)
+    const next = () => page = Math.min(maxPage, page + 1)
+
+    const updateSort = (func) => {
+        if (sorting.base === func) {
+            if (sorting.direction === "desc") {
+                sorting = noSort
+                return
+            }
+            sorting = {
+                func: (a, b) => -func(a, b),
+                base: func,
+                direction: "desc"
+            }
+            return
+        }
+        sorting = {
+            func,
+            base: func,
+            direction: "asc",
+        }
+    }
+    const updateFilter = (func, value) => {
+        if (func === null) {
+            return
+        }
+        filters.set(func, value)
+        filterFunctions = [
+            ...filters.entries()
+        ]
+    }
+
+    const context = writable({})
+    $: $context = {
+        updateSort,
+        fillHeader,
+        sorting,
+        updateFilter,
+    }
+    setContext(dtContext, context)
+
+    const fire = createEventDispatcher()
+    const pass = handler$(
+        (row) => fire("row-click", row)
+    )
+
+    let scroller = null
+    $: if (scroller !== null && isNaN(page) === false) {
+        scroller.scrollTop = 0
+    }
+    const jump = (evt) => {
+        if (evt.type === "keypress" && evt.key !== "Enter") {
+            return
+        }
+        const target = parseInt(evt.target.value)
+        if (isNaN(target) === true) {
+            jumpTarget = (page + 1).toString()
+            return
+        }
+        page = Math.max(
+            Math.min(jumpTarget - 1, maxPage),
+            0
+        )
+        jumpTarget = (page + 1).toString()
+    }
+
+    $: content = {
+        "fl.cross": "stretch",
+        p: "0px",
+        gap: "0px",
+        over: (scrollable === true) ? "auto" : null,
+    }
+    $: header = {
+        "h.min": rowHeight,
+        y: "0px",
+        z: "+10",
+        pos: (scrollable === true) ? "sticky" : null,
+    }
+</script>
+
+<Paper {color} h={height}>
+    <ws-flex use:wsx={content} slot="content" bind:this={scroller}>
+        <Table data={rows} {color} {fillHeader} {...$$restProps} b.t.w="0px">
+            <tr use:wsx={header} slot="header">
+                <slot name="header">
+                    <th>No Header Defined</th>
+                </slot>
+            </tr>
+            <tr ws-x="[h {rowHeight}]" slot="row" let:row>
+                <slot name="row" {row}>
+                    <th>No Row Defined</th>
+                </slot>
+            </tr>
+            <tr ws-x="[h {rowHeight}]" slot="empty-row" />
+        </Table>
+    </ws-flex>
+    <Grid slot="footer" gr.cols="min-content min-content min-content 1fr"
+    rows="32px" b="1px solid @color" b.b.w="4px">
+        {#if pageCount > 0}
+            <Button on:click={prev} disabled={page === 0}>
+                <Icon name="arrow-big-left" />
+            </Button>
+            <Button on:click={next} disabled={page === maxPage}>
+                <Icon name="arrow-big-right" />
+            </Button>
+            <Text adorn t.ws="nowrap">
+                Page
+                <input ws-x="[b 1px solid @text-color-normal] [w 36px] [r 4px]
+                [h 24px] [bg.c transaprent] [t.a center] [m.l 4px] [m.r 4px]"
+                type="text" bind:value={jumpTarget}
+                on:keypress={jump} on:blur={jump} />
+                / {pageCount}
+            </Text>
+        {:else}
+            <div ws-x="[col span 3] [p.l 4px]">
+                No data to show
+            </div>
+        {/if}
+        <slot name="action" />
+    </Grid>
+</Paper>

package/src/composed/entry-button.md

@@ -1,34 +1,44 @@
-# EntryButton
-
-The EntryButton is a convenient way to display modals and screens over
-content without needing to bind variables have lots of Modal elements in
-addition to the buttons that show them.
-
-## Props
-
-- ### component
-    The component to show when clicked
-- ### props
-    The props to pass to the component when it is shown, or a function that
-    generates the props when called
-- ### this
-    The wrapper for the component. Default is Modal but any component that
-    has the same interface as Modal will work
-
-## Events
-- ### entry
-    When the component is close the entry event is fired. The detail
-    property of the event will have the value from closing it
-
-## Example
-```svelte
-<EntryButton component={Subscreen} on:entry={console.log}>
-    Open Subscreen
-</EntryButton>
-<EntryButton component={CoolDialog} on:entry={console.log}>
-    Open Subscreen
-</EntryButton>
-<EntryButton this={CoolModal} component={CustomThing} on:entry={console.log}>
-    Open Subscreen
-</EntryButton>
-```
+# EntryButton
+
+The EntryButton is a convenient way to display modals and screens over
+content without needing to bind variables have lots of Modal elements in
+addition to the buttons that show them.
+
+## Props
+
+### component
+The component to show when clicked
+
+### props
+The props to pass to the component when it is shown, or a function that
+generates the props when called.
+
+### this
+The wrapper for the component. Default is [Modal](../layout/modal.md) but any
+component that has the same interface as Modal will work.
+
+## Events
+
+### entry
+When the component is closed the entry event is fired. The detail
+property of the event will have the value from closing it.
+
+## Example
+```svelte
+<script>
+    const propsFunc = () => ({
+        now: Date.now(),
+        rand: Math.random(),
+    })
+</script>
+
+<EntryButton component={Subscreen} on:entry={console.log}>
+    Open Subscreen
+</EntryButton>
+<EntryButton component={CoolDialog} props={{ thing: true }} on:entry={console.log}>
+    Open Subscreen
+</EntryButton>
+<EntryButton this={CoolModal} component={CustomThing} on:entry={console.log} props={propsFunc}>
+    Open Subscreen
+</EntryButton>
+```