# Getting Started

    library(bs4Dashkit)

## Overview

`bs4Dashkit` extends `{bs4Dash}` by standardizing branding, sidebar behavior, navbar utilities, and theme customization. Every feature is optional — you can adopt as little or as much as you need.

The package is organised around four areas:

1. Brand and sidebar — `dash_titles()` + `use_bs4Dashkit_core()`
2. Theming — `use_dash_theme()` and named presets
3. Navbar — `dash_nav_title()`, refresh / help buttons, and user menu
4. Footer — `dash_footer()` with flexible logo and text positioning

## Minimal example

The smallest possible `bs4Dashkit` app requires exactly two calls beyond normal `bs4Dash` boilerplate:

    library(shiny)
    library(bs4Dash)
    library(bs4Dashkit)

    # 1. Build the brand object
    ttl <- dash_titles("My Dashboard", icon = icon("cloud"))

    ui <- bs4DashPage(
      title   = ttl$app_name,           # browser tab title
      header  = bs4DashNavbar(title = ttl$brand),
      sidebar = bs4DashSidebar(),
      body    = bs4DashBody(
        use_bs4Dashkit_core(ttl)        # 2. always the first call in body and called once
      )
    )

    server <- function(input, output, session) {}
    shinyApp(ui, server)

`dash_titles()` accepts a single string and sensible defaults handle everything else. When no icon is supplied, the sidebar brand defaults to text-only modes. `use_bs4Dashkit_core()` loads the CSS dependencies, activates the sidebar brand mode, and applies the default theme.

If you prefer, you can also pass a simple `shiny::icon()` tag:

    ttl <- dash_titles(
      brand_text = "My Dashboard",
      icon = icon("cloud")
    )

## `dash_titles()` — the brand object

`dash_titles()` is the single entry point for all brand-related configuration. It returns a named list with three slots:

Slot | Where it goes
--- | ---
`ttl$app_name` | `bs4DashPage(title = ...)`
`ttl$brand` | `bs4DashNavbar(title = ...)`; the sidebar brand mirrors this automatically in a standard `bs4DashPage()`
`ttl$deps` | inside `bs4DashBody(...)` (handled automatically by `use_bs4Dashkit_core()`)

    ttl <- dash_titles(
      brand_text     = "OLTCR Dashboards",
      icon           = icon("project-diagram"),
      weight         = 700,
      effect         = "shimmer",          # "none" | "glow" | "shimmer" | "emboss"
      glow_color     = "#2f6f8f",
      size           = "20px",
      collapsed      = "icon-text",
      expanded       = "icon-text",
      collapsed_text = "OLT",              # shown when sidebar is collapsed
      expanded_text  = "OLTCR Dashboards",
      brand_divider  = TRUE
    )

`brand_text` is the primary label for the app. It is always used for the navbar brand and is also the default expanded sidebar label. Use `expanded_text` only when the expanded sidebar should say something different, and use `collapsed_text` when the collapsed sidebar needs a shorter label. In practice, about 3 characters works best in the narrow collapsed sidebar.

If you want a fully textless icon brand, set `brand_text = NULL` and keep both sidebar states at `"icon-only"`:

    ttl <- dash_titles(
      brand_text = NULL,
      app_name   = "Icon Lab",
      icon       = icon("cloud"),
      collapsed  = "icon-only",
      expanded   = "icon-only"
    )

Alternatively, use an image instead of a Font Awesome icon:

    ttl <- dash_titles(
      brand_text = "My App",
      icon_img   = "logo.png",        # overrides `icon`
      icon_shape = "rounded"              # "circle" | "rounded" | "square"
    )

NB: Place logo.png in your app’s www/ directory.

## `use_bs4Dashkit_core()` — the core entry point

Always place this as the first element inside `bs4DashBody()`. It:

- Injects the package CSS and JavaScript
- Activates the sidebar brand mode logic
- Applies a theme preset (default: `"professional"`)

    body = bs4DashBody(
      use_bs4Dashkit_core(ttl, preset = "professional"),
      # ... rest of your content
    )

Available presets:

    use_bs4Dashkit_core(ttl, preset = "professional")  # cool blue-grey (default)
    use_bs4Dashkit_core(ttl, preset = "modern")        # brighter accent colours
    use_bs4Dashkit_core(ttl, preset = "dark-lite")     # dark surfaces and lighter text
    bs4dashkit_theme_presets()                         # list built-in presets

For a runnable template app, use:

    app <- bs4dashkit_example_app()

For a fuller interactive playground that exercises sidebar states, hover behavior, presets, navbar controls, and footer styling together, use:

    app <- bs4dashkit_demo_app()

You can also launch the packaged example directory directly:

    shiny::runApp(system.file("examples", "real-shiny-app", package = "bs4Dashkit"))

That packaged example contains the full app code directly in `inst/examples/real-shiny-app/app.R`, so it can be read, modified, and run as a standalone reference app.

There is also a heavier shipped example that exercises the navbar title alignment controls, sidebar text sizing and weights, icon-only branding, and theme presets together:

    shiny::runApp(system.file("examples", "test-all", package = "bs4Dashkit"))

## Sidebar modes

The sidebar brand area can show different content depending on whether the sidebar is collapsed or expanded. Set these in `dash_titles()`:

    ttl <- dash_titles(
      brand_text     = "OLTCR Dashboards",
      icon           = icon("chart-line"),
      collapsed      = "icon-only",       # just the icon when narrow
      expanded       = "icon-text",       # icon + label when wide
      collapsed_text = "OLT",
      expanded_text  = "OLTCR Dashboards" # optional; brand_text is the default
    )

Mode | Collapsed | Expanded
--- | --- | ---
`"icon-only"` | ✓ | ✓
`"icon-text"` | ✓ | ✓
`"text-only"` | ✓ | ✓

Add hover-expand behavior (sidebar expands on mouse-over even when collapsed):

    body = bs4DashBody(
      use_bs4Dashkit_core(
        ttl,
        preset = "professional",
        topbar_h = 56,
        collapsed_w = 4.2,
        expanded_w = 250
      )
      # ...
    )

NB: `use_dash_sidebar_behavior()` is included by `use_bs4Dashkit_core()`. Call it directly only if you are not using the core helper.

Hover-expand behavior is included by `use_bs4Dashkit_core()`. Configure it via `topbar_h`, `collapsed_w`, and `expanded_w`. Call `use_dash_sidebar_behavior()` directly only when not using the core helper.

## Global options

Set package-level defaults once (e.g. in your `global.R`) so every app in a project inherits them:

    options(
      bs4Dashkit.sidebar.collapsed = "icon-only",
      bs4Dashkit.sidebar.expanded  = "icon-text",
      bs4Dashkit.brand_divider     = TRUE,
      bs4Dashkit.accent            = "#2f6f8f",
      bs4Dashkit.theme_preset      = "professional"
    )

If `preset = NULL`, `use_bs4Dashkit_core()` uses the package option `bs4Dashkit.theme_preset (if set)`. If `accent = NULL`, it uses `bs4Dashkit.accent`.

    use_bs4Dashkit_core(ttl, preset = NULL) # uses option if set
    use_bs4Dashkit_core(ttl, accent = NULL) # uses option if set

`dash_titles()` reads these options when the corresponding arguments are `NULL`, so you can omit them from individual calls.

## Troubleshooting

- “I see 404s for dash-theme.css” -> call use_bs4Dashkit_core() or use_bs4Dashkit() first (resource path)

- “My icon doesn’t show” -> check Font Awesome name / include icon_img

- “Hover expand doesn’t work on mobile”-> expected (touch devices)

- “Sidebar labels do not match the hover-expanded state” -> update to the current package version so the shipped hover-expanded sidebar rules are used

## What next?

- Branding and sidebar modes — full reference for all `dash_titles()` arguments
- Theming and presets — CSS variable overrides and custom presets
- Navigation utilities — refresh, help, user menu, and `dash_nav_title()`
- Footer — all footer layout combinations
- Complete example app — a single app that exercises every feature