openguessr-ui 0.1.0 → 0.2.0

package/README.md

@@ -13,17 +13,17 @@ These core concepts define how UI should be structured.
 
 ### Core concepts
 
-- **Boxes:** Boxes house controls, text, or other boxes.
+- **Boxes:** Boxes house controls, text, images, or other boxes.
 
-- **Panels:** Panels are flexible floating UI elements. They typically include controls (e.g. buttons) rather than loads of text or images, perfect for HUDs.
+- **Panels:** Panels are used for floating UI. They typically include controls rather than loads of text or images, perfect for HUDs.
 
-- **Containers:** Containers contain boxes. The popup acts as a layout/container hybird that also contains boxes.
+- **Containers:** Containers contain boxes. The popup acts as a layout/container hybrid that also contains boxes.
 
 - **Layouts:** Layouts are typically full pages that containers or panels sit in.
 
 ### Hierarchy
 
-1. Every element starts in layout space (level 1), where `--layout-margin` defines the spacing between grouped elements (and `--layout-spacer` between unrelated ones), padding, and border radii of children.
+1. Every element starts in layout space (level 1), where `--layout-margin` defines the spacing between grouped elements, the padding, and the border radii of children. For separating unrelated elements, `--layout-spacer` is used.
 
 2. The second level is containers, where the spacing and padding is `--box-margin`, and the border radii of children are as well.
 
@@ -31,9 +31,9 @@ These core concepts define how UI should be structured.
 
 4. On the fourth level there is either content or smaller boxes. Smaller boxes still use `--box-margin` for padding and spacing, but `--content-margin` for border radii.
 
-The content level (inside buttons, chips, tabs, or other controls) uses spacing of `--content-margin`. Placing content directly into layouts or containers is not allowed, it **needs** to sit inside a box or panel.
+The content level (inside buttons, chips, tabs, or other controls) uses spacing of `--content-margin`. Placing content directly into layouts or containers is not allowed, it needs to sit inside a box or panel.
 
-Popups take some properties from layouts and some from containers. They use `--layout-margin` for spacing, but content inside them is boxes (level 3) with `--box-margin` for border radii. Panels typically live in layout space (level 1), but have unique spacing rules (as outlined above).
+Popups take some properties from layouts and some from containers. They use `--layout-margin` for spacing, but content inside them is boxes (level 3) with `--box-margin` for border radii.
 
 ## Styling
 
@@ -64,25 +64,25 @@ These variables are used for colors:
 | --overlay-color | Dark overlays |
 | --overlay-color-dark | Full-screen menu overlays |
 | --bright-green-color | Experience, perks |
-| --bright-green-color-soft| Indicators, subtle |
+| --bright-green-color-soft| Indicators |
 | --bright-green-color-dark | Experience, perk backgrounds |
 | --background-color | Opaque background |
 | --dark-shadow-color | Text or drop shadows |
 
 > [!TIP]
-> There should be at most one `--brand-color` element visible at a time (the primary action). Green colors should **not** be used for success, use bright styling instead (e.g. `rgba(255, 255, 255, 0.2)`).
+> There should be at most one `--brand-color` element visible at a time (the primary action). Green colors should not be used for success, use bright styling instead (e.g. `rgba(255, 255, 255, 0.2)`).
 
-These variabels are used for box shadows:
+These variables are used for box shadows:
 
 | Variable | Used for |
 | -------- | ------- |
 | --button-shadow | Buttons |
-| --button-shadow-dark | Subtle buttons |
+| --button-shadow-dark | Dark buttons |
 | --box-shadow-top | Boxes that fade out towards the bottom |
 | --box-shadow-bottom | Boxes that fade out towards the top |
 | --box-shadow | Boxes |
 | --bulb-shadow | Pills, chips, badges |
-| --panel-shadow | Floating elements (containers, panels..) |
+| --panel-shadow | Floating elements (containers, panels etc.) |
 
 These variables are used for blur:
 
@@ -108,11 +108,11 @@ Boxes typically use this base styling:
 }
 ```
 
-Their width should not grow to fit their container or the Popup they are in.
+Their width shouldn't grow to fit the container or popup they are in.
 
 #### Text inside boxes
 
-Since boxes have rather tight padding and text naturally adds top and bottom spacing through the line-height, applying `padding-inline: var(--content-margin)` to text is recommended. If the entire box just contains text, raising the boxes' inline padding to `--layout-margin` has the same effect.
+Since boxes have rather tight padding and text naturally adds top and bottom spacing through the line-height, applying `padding-inline: var(--content-margin)` to text is recommended. If the entire box just contains text, raising the box's inline padding to `--layout-margin` has the same effect.
 
 ### Panels
 
@@ -131,7 +131,7 @@ Panels typically use this base styling:
 
 Panels that house large buttons which are rounder than usual buttons should have a border radius of `--layout-margin` to avoid uneven corners. Don't mix them, panels should stick to only large or only small buttons.
 
-When panels sit inside layouts with a strong background color (e.g. `--overlay-color-dark`), their backgorund color should be `--box-color` instead of `--panel-color` to avoid layering two blue-ish tones (which will produce a color that looks too vibrant).
+When panels sit inside layouts with a strong background color (e.g. `--overlay-color-dark`), their background color should be `--box-color` instead of `--panel-color` to avoid layering two blue-ish tones (which will produce a color that looks too vibrant).
 
 The gap or margin between related panels should be `--box-margin` if they use `--box-margin` for the border radii, otherwise `--layout-margin`.
 
@@ -169,7 +169,7 @@ Layouts typically use this base styling:
 
 ### Buttons
 
-Buttons should always be placed in a box or panel, not just on a blank page. Large buttons should **not** be put into a box.
+Buttons should always be placed in a box or panel, not just on a blank page. Large buttons shouldn't be put into a box.
 
 To create a button, apply the `standard-button` class. This will create a red primary button. To make it secondary, add `bright`.
 
@@ -181,7 +181,7 @@ Large buttons with short text inside often look unnaturally slim when placed as
 
 Regular buttons typically have the icon placed on the left side. 
 
-Large buttons with text place the icon towards the right and use `space-between` to ensure that when multiple buttons are present, icons and text are perfectly aligned below each other, making it easier to scan through them at a glance.
+Large buttons with text place the icon towards the right and use `space-between` to ensure that when multiple buttons are present in a stack, icons and text are perfectly horizontally aligned, making it easier to scan through them at a glance.
 
 ### Icons
 
@@ -197,7 +197,7 @@ The spacing between text and an icon inside content should be `--content-margin`
 
 ### Scrollable areas
 
-Overfade (`overfade`) is a library used for scrollable areas. It applies a dynamic mask-image on the overflowing element's parent.
+Overfade (`overfade`) is a library used for scrollable areas. It applies a dynamic mask-image to the scroll container, the element that holds the overflowing content.
 
 For example, when an element, that contains overflowing text content and uses `of-top` and `of-bottom`, is scrolled all the way to the top, the top of the text is not faded out, only the bottom is.
 
@@ -213,6 +213,8 @@ These classes should not be applied directly on boxes or containers, since that
 
 Scrollable content should be intentionally, visibly cut off when scrolling is allowed to communicate the fact that scrolling is possible.
 
+Typically, scroll bars should be hidden via `scrollbar-width: none`. There can be exceptions, e.g. for text editors where a scroll bar brings utility.
+
 ### Opacity values
 
 Opacity values used are typically `0.25`, `0.5`, `0.75` and `1`. Supportive text, such as the explanation for a feature, can be `0.75` or even `0.5`. Labels, e.g. for controls, should be full opacity.
@@ -240,7 +242,7 @@ The popup component is used for dialogs. It takes the following props:
 - `open`: Whether the popup is open
 - `slim`: Reduces the max width
 - `verySlim`: Reduces the max width further
-- `frameless`: Reduces the padding, e.g. for iFrames
+- `frameless`: Reduces the padding, e.g. for iframes
 - `onuserclose`: Called when the user closes the popup
 
 A common design pattern is to include a heading at the top of a popup. For this, the built-in `popup-title` class can be used:
@@ -263,7 +265,7 @@ The chip component is used for small pieces of information, such as a "New" or "
 - `italic`: Makes the text italic, typically combined with red
 - `mutedOpacity`: Makes the text muted, red variant typically disables this
 - `onclick`: Makes the chip clickable
-- `class`, `style`: Class passthrough
+- `class`, `style`: Class and style passthrough
 
 ### Collapsible
 
@@ -299,7 +301,7 @@ showConfirmPopup("Remove item?", "The item will be removed from your favorites."
 
 The error popup component is used to inform the user about errors. It needs to be mounted.
 
-Error popups are shown via `errorPopup(title, description, errorCode, reload, hideDontShowAgainOption)`:
+Error popups are shown via `showErrorPopup(title, description, errorCode, reload, hideDontShowAgainOption)`:
 
 - `title`: The popup title
 - `description`: The description
@@ -310,7 +312,7 @@ Error popups are shown via `errorPopup(title, description, errorCode, reload, hi
 Usage example:
 
 ```js
-errorPopup("Failed to load map", "An error occured loading this map.", "Code 404: Map not found");
+showErrorPopup("Failed to load map", "An error occurred loading this map.", "Code 404: Map not found");
 ```
 
 ### InfoBanner
@@ -361,7 +363,7 @@ The room code input component is used for entering 6-character room codes. It ta
 
 - `segments`: The entered characters
 - `inPage`: Set to false when used in panels, boxes etc.
-- `onsubmit`: Called with the code when enter or the submit button is pressed
+- `onsubmit`: Called with the code when Enter or the submit button is pressed
 
 ### Tabs
 
@@ -382,16 +384,17 @@ The ticker component is used for fine-grained numeric inputs. It takes the follo
 - `value`: Current value
 - `initialValue`: Start value
 - `step`: Step amount (how much the value changes per step)
-- `minimum`: Maximum value
-- `minimumText`, `maximumText`: Text displayed when the max/min is reached
-- `minimumValue`, `maximumValue`: Custom value to show when max/min is reached
+- `minimum`: Minimum value
+- `maximum`: Maximum value
+- `minimumText`, `maximumText`: Text displayed when the min/max is reached
+- `minimumValue`, `maximumValue`: Custom value to bind when the min/max is reached
 - `note`: Unit of the value
 - `minValueWidth`: Minimum width of value field to prevent the width from jumping
 - `onchange`: Called when the value changes
 
 ### TitleSeparator
 
-The title separator component is used to separate content inside Popups or containers. It takes the following props:
+The title separator component is used to separate content inside popups or containers. It takes the following props:
 
 - `text`: The title text
 - `noMargin`: Removes the default top and bottom margin (`--layout-margin`)
@@ -411,6 +414,8 @@ Usage example:
 <button {@attach tooltip({ text: "Settings" })}><GearsIcon /></button>
 ```
 
+Options:
+
 - `text`: The tooltip text
 - `imageSrc`: Image shown above the text
 - `imageAspectRatio`: Aspect ratio of the image
@@ -423,10 +428,12 @@ Usage example:
 
 ## Sound effects
 
-UI sound effects are available as `.ogg` files and can be played with any audio library:
+UI sound effects are available as `.ogg` files and can be played with any audio library. The `sounds` export maps each name to its file URL:
 
 ```js
-import basicButtonSound from "openguessr-ui/sound-effects/basic_button.ogg";
+import { sounds } from "openguessr-ui";
+
+new Audio(sounds.basic_button).play();
 ```
 
 | Sound | Purpose |
@@ -434,20 +441,18 @@ import basicButtonSound from "openguessr-ui/sound-effects/basic_button.ogg";
 | basic_button | Default sound for standard buttons and tabs |
 | juicy_button | Selection-like choices (e.g. map selection) |
 | start_button | Starting or joining a game |
-| toggle_button | Anything that toggles, e.g. collapsibles |
-| change_value | Changing a value, e.g. the ticker |
-| item_select | Selecting an item, e.g. a pin, badge, or flag |
+| toggle_button | Anything that toggles (e.g. collapsibles) |
+| change_value | Changing a value (e.g. through a ticker) |
+| item_select | Selecting an item (e.g. a pin, badge, or flag) |
 | item_locked | Trying to select a locked item |
 
-The components don't play sounds themselves. Instead, play them via their callbacks:
+The components don't play sounds themselves. Instead, they should be played via callbacks:
 
 - Collapsible `ontoggle`: `toggle_button`
 - Ticker `onchange`: `change_value`
+- Tabs `onchange`: `basic_button`
 - Notification `onaccept`, `ondismiss`: `basic_button`
-
-## Scroll bars
-
-Typically, scroll bars should be hidden via `scrollbar-width: none`. There can be exceptions, e.g. for text editors where a scroll bar brings utility.
+- ConfirmPopup `onconfirm`: `basic_button`
 
 ## Text formatting guidelines
 

package/errorPopup.svelte.js

@@ -8,7 +8,7 @@ export const errorPopupState = $state({
   reload: false
 });
 
-export function errorPopup(popupTitle, popupDescription, popupErrorCode, reloadPopup, hideDontShowAgainOption) {
+export function showErrorPopup(popupTitle, popupDescription, popupErrorCode, reloadPopup, hideDontShowAgainOption) {
   errorPopupState.hideDisableOption = hideDontShowAgainOption;
 
   // If errors should be shown or it is a critical error that needs a reload, show the popup

package/index.js

@@ -13,4 +13,15 @@ export { default as TitleSeparator } from "./components/TitleSeparator.svelte";
 export { tooltip } from "./tooltip.svelte.js";
 export { showNotification } from "./notifications.svelte.js";
 export { showConfirmPopup } from "./confirmPopup.svelte.js";
-export { errorPopup } from "./errorPopup.svelte.js";
+export { showErrorPopup } from "./errorPopup.svelte.js";
+
+// Sounds
+import basic_button from "./sound-effects/basic_button.ogg";
+import juicy_button from "./sound-effects/juicy_button.ogg";
+import start_button from "./sound-effects/start_button.ogg";
+import toggle_button from "./sound-effects/toggle_button.ogg";
+import change_value from "./sound-effects/change_value.ogg";
+import item_select from "./sound-effects/item_select.ogg";
+import item_locked from "./sound-effects/item_locked.ogg";
+
+export const sounds = { basic_button, juicy_button, start_button, toggle_button, change_value, item_select, item_locked };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "openguessr-ui",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"scripts": {
 		"dev": "vite example"
@@ -28,7 +28,6 @@
 		"./variables.css": "./variables.css",
 		"./base.css": "./base.css",
 		"./classes.css": "./classes.css",
-		"./sound-effects/*": "./sound-effects/*",
 		"./fonts/*": "./fonts/*"
 	},
 	"peerDependencies": {