diff --git a/.github/workflows/publish_npm_release.yml b/.github/workflows/publish_npm_release.yml index 23ad88e1..2259bf32 100644 --- a/.github/workflows/publish_npm_release.yml +++ b/.github/workflows/publish_npm_release.yml @@ -6,9 +6,7 @@ on: - 'v*.*.*' permissions: - contents: write - pages: write - id-token: write + contents: read jobs: publish: @@ -153,43 +151,6 @@ jobs: git commit -m "docs: snapshot ${DOCS_VERSION} release docs" git push origin HEAD:main - build_docs: - runs-on: ubuntu-latest - name: Build release docs - needs: - - publish - - snapshot_docs - if: always() && needs.publish.result == 'success' && (needs.snapshot_docs.result == 'success' || needs.snapshot_docs.result == 'skipped') - steps: - - uses: actions/checkout@v6 - with: - ref: main - - - name: Setup node - uses: actions/setup-node@v6 - with: - node-version: '20.19' - cache: 'npm' - - - name: Install dependencies - run: npm ci - - - name: Build docs site - run: npm run docs:build - - - name: Upload Pages artifact - uses: actions/upload-pages-artifact@v3 - with: - path: docs/build - - deploy_docs: - runs-on: ubuntu-latest - name: Deploy release docs - needs: build_docs - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + # Docs deployments must come from main because the github-pages environment + # is protected against tag refs. When a release needs a new versioned docs + # snapshot, this workflow pushes it to main and deploy-docs.yml publishes it. diff --git a/Gruntfile.js b/Gruntfile.js index 4977b95c..e40324ea 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -148,15 +148,6 @@ module.exports = function (grunt) { '**/*' ], dest: 'docs/static/dist/' - }, - { - expand: true, - cwd: 'node_modules/@fortawesome/fontawesome-free/', - src: [ - 'css/all.min.css', - 'webfonts/*' - ], - dest: 'docs/static/vendor/fontawesome/' } ] } diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 4ce23df2..d48c8104 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -41,6 +41,7 @@ const config = { stylesheets: [ 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css', + 'https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@7.2.0/css/all.min.css', withBaseUrl('dist/css/bootstrap-select.min.css') ], diff --git a/docs/src/components/LiveExample.js b/docs/src/components/LiveExample.js index 87db7966..46048786 100644 --- a/docs/src/components/LiveExample.js +++ b/docs/src/components/LiveExample.js @@ -48,8 +48,6 @@ function LiveExampleInner ({ html, className = '', style }) { return; } - destroyInstances(); - // Keep the marker class in place so a remount can't strand the examples // as plain selects before the assets finish loading. instances = Array.from(exampleRef.current.querySelectorAll('select.selectpicker')).map(function (select) { diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 3df5e3b3..5aae99dc 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -1,5 +1,4 @@ @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap'); -@import url('../../../node_modules/@fortawesome/fontawesome-free/css/all.min.css'); :root { --ifm-color-primary: #181618; diff --git a/docs/static/examples/tags-editor.html b/docs/static/examples/tags-editor.html index 408065a7..30bd8c78 100644 --- a/docs/static/examples/tags-editor.html +++ b/docs/static/examples/tags-editor.html @@ -5,7 +5,7 @@ bootstrap-select tags editor example - + diff --git a/docs/versioned_docs/version-1.0/css/custom.css b/docs/versioned_docs/version-1.0/css/custom.css new file mode 100644 index 00000000..680e41b7 --- /dev/null +++ b/docs/versioned_docs/version-1.0/css/custom.css @@ -0,0 +1,339 @@ +html { + position: relative; + min-height: 100%; +} +body { + padding-top: 56px; + /* Margin bottom by footer height */ + margin-bottom: 64px; +} +label { + display: block; +} +/* hide "Home" in navbar */ +.nav.navbar-nav:first-child > li:first-child { + display: none; +} + +ul.nav li.main { + font-weight: normal; +} + +.footer { + position: absolute; + bottom: 0; + width: 100%; + /* Set the fixed height of the footer here */ + height: 64px; + background-color: #f5f5f5; +} + +.footer .container .text-muted { + margin: 20px 0; +} + +.footer .container { + padding-right: 15px; + padding-left: 15px; +} + +/* Outline button for use within the docs */ +.btn-outline { + color: #337ab7; + background-color: transparent; + border-color: #337ab7; +} +.btn-outline:hover, +.btn-outline:focus, +.btn-outline:active { + color: #fff; + background-color: #337ab7; + border-color: #337ab7; +} + +/* Inverted outline button (white on dark) */ +.btn-outline-inverse { + color: #fff; + background-color: transparent; + border-color: #fff; +} +.btn-outline-inverse:hover, +.btn-outline-inverse:focus, +.btn-outline-inverse:active { + color: #337ab7; + text-shadow: none; + background-color: #fff; + border-color: #fff; +} + +.bs-docs-header { + background: #337ab7; + color: #fff; +} + +.bs-docs-header .btn { + padding: 15px 30px; + font-size: 20px +} + +.bs-docs-header h1 { + margin-bottom: 20px; +} + +.bs-docs-header .lead { + margin: 0 auto 30px; + line-height: 1.5; +} + +.bs-docs-sub-header { + padding-top: 20px; + padding-bottom: 20px; +} + +.gh-btns { + margin: 48px 0 -30px; + background: rgba(0,0,0,.1); + padding: 20px 0 15px; +} + +.content h1:first-of-type, +.content h1:first-of-type + p:first-of-type { + text-align: center; +} + +.bs-docs-example > p { + margin-top: 20px; +} + +.bs-docs-example > p:last-child { + margin-bottom: 0; +} + +.bs-docs-example .table, +.bs-docs-example .progress, +.bs-docs-example .well, +.bs-docs-example .alert, +.bs-docs-example .hero-unit, +.bs-docs-example .pagination, +.bs-docs-example .navbar, +.bs-docs-example > .nav, +.bs-docs-example blockquote { + margin-bottom: 5px; +} + +.bs-docs-example .pagination { + margin-top: 0; +} + +.special { + font-weight: bold !important; + color: #fff !important; + background: #bc0000 !important; + text-transform: uppercase; +} + +.bs-docs-example { + position: relative; + padding: 15px; + margin: 0 -15px 15px; + border-color: #f7f7f9; + border-style: solid; + border-width: 1px 0; + -webkit-box-shadow: inset 0 3px 6px rgba(0,0,0,.05); + box-shadow: inset 0 3px 6px rgba(0,0,0,.05); +} + +.highlight { + padding: 9px 14px; + margin-bottom: 14px; + background-color: #f7f7f9; + border-radius: 0; + margin-left: -15px; + margin-right: -15px; +} + +.bs-docs-example + .highlight, +.highlight-before .highlight { + margin: -15px -15px 15px; + border-width: 0; +} + +.highlight + .bs-docs-example { + margin: -15px -15px 15px; + border-width: 0 0 4px; + border-radius: 0; +} + +.carbonad { + margin-top: 60px; + max-width: 400px; + margin-left: auto; + margin-right: auto; +} + .carbonad-inner { + width: auto!important; + height: auto!important; + padding: 20px!important; + overflow: hidden; + font-size: 13px!important; + line-height: 16px!important; + text-align: left; + background: rgba(0, 0, 0, 0.05); + border: none !important; + border-width: 1px 0!important; +} + .carbon-poweredby, +.carbon-text { + display: block!important; + float: none!important; + width: auto!important; + height: auto!important; + margin-left: 145px!important; + font-family: "Helvetica Neue",Helvetica,Arial,sans-serif!important; + color: rgba(255, 255, 255, 0.75) !important; +} + .carbon-poweredby { + float: left; + margin-top: 9px; + text-align: left; + width: 142px; + opacity: 0.5; +} + .charity { + opacity: 0.5; + padding: 4px; + margin-bottom: -31px; + font-size: 14px; +} + .charity a { + color: #fff; +} + .carbon-img img { + border: none; + display: inline; + float: left; + height: 100px; + margin: 0 !important; + width: 130px; +} + +.logo-block a { + display: block; + padding: 5px; + margin: 5px 0; +} + +.logo-block img { + height: auto; + max-width: 100%; + max-height: 40px; +} + +.logo-container { + float: left; + max-width: 25%; + margin: 0 15px; +} + +.logo-block + div { + margin: 5px 0; +} + +.carbonad-header { + position: static; + display: block; + margin: 2rem 0; + overflow: hidden; + font-size: .8125rem; + line-height: 1.4; + text-align: left; +} + +@media (min-width: 480px){ + .charity { + margin-bottom: 0; + } + + .logo-container { + max-width: 60%; + } +} + +@media (min-width: 576px) { + .carbonad-header { + border-radius: 4px; + margin: -100px 0 -51px auto; + } +} + +@media (min-width: 768px) { + .carbonad:not(.carbonad-header) { + margin-top: 80px; + max-width: 330px; + margin-bottom: -3rem; + } + + .carbonad-inner { + width: 330px!important; + margin: 50px auto 0 !important; + border-width: 1px!important; + border-radius: 4px; + } + .highlight { + margin-left: 0; + margin-right: 0; + } + .bs-docs-example { + margin-right: 0; + margin-left: 0; + background-color: #fff; + border-color: #f7f7f9; + border-width: 4px; + border-radius: 0; + -webkit-box-shadow: none; + box-shadow: none; + } + + .bs-docs-example.no-code { + border-radius: 0; + } + + .bs-docs-example + .highlight { + margin-top: -16px; + margin-right: 0; + margin-left: 0; + border-width: 1px; + } + + .highlight + .bs-docs-example { + margin-top: -16px; + margin-right: 0; + margin-left: 0; + border-width: 4px; + } + + .logo-container { + max-width: 33.3333%; + } + + .gh-btns { + margin-bottom: -63px; + } +} + +@media (min-width: 992px){ + .bs-docs-header .lead { + width: 80%; + } + + .carbonad-inner { + top: 0; + right: 15px; + width: 330px!important; + padding: 15px!important; + } + + .logo-container { + max-width: 25%; + } +} \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0/examples.mdx b/docs/versioned_docs/version-1.0/examples.mdx new file mode 100644 index 00000000..2a6a0ea2 --- /dev/null +++ b/docs/versioned_docs/version-1.0/examples.mdx @@ -0,0 +1,952 @@ +--- +sidebar_position: 2 +title: Examples +description: Live bootstrap-select examples hosted by the Docusaurus docs site. +--- + +import LiveExample from '@site/src/components/LiveExample'; + +# Basic examples + +:::info CrestApps fork +The examples use the vanilla JavaScript / Bootstrap 5+ API: `new Selectpicker(el)` or the `selectpicker` class, which auto-initializes. jQuery is not required. +::: + +
+
+

Standalone basic

+

Open the local plugin build on a plain HTML page.

+ Open basic example +
+
+

Live search

+

Test search filtering against hosted example markup.

+ Open live search +
+
+

Multiple select

+

Verify multiselect and action-box behavior.

+ Open multiselect +
+
+ +## Standard select boxes + +Make this:

+ + + +

Become this:

+ + `} +/> + +```html + +``` + + + +## Select boxes with optgroups + + + + + + + + + + + + + `} +/> + +```html + +``` + +## Multiple select boxes + + + + + + `} +/> + +```html + +``` + +# Live search + +--- + +## Live search + +You can add a search input by passing `data-live-search="true"` attribute: + + + + + + `} + className="no-code" +/> + +## Key words + +Add key words to options to improve their searchability using `data-tokens`. + + + + + + `} +/> + +```html + +``` + +# Limit the number of selections + +Limit the number of options that can be selected via the `data-max-options` attribute. It also works for option groups. Customize the message displayed when the limit is reached with `maxOptionsText`. + + + + + + + + `} +/> + +```html + + + +``` + +# Custom button text + +--- + +## Placeholder +

+Use the `placeholder` attribute to set the default placeholder text when nothing is selected. This works for both multiple and standard select boxes: + + + + + + +
+ + +
`} +/> + +```html + +``` + +## Selected text + +

+Set the `title` attribute on individual options to display alternative text when the option is selected: + + + + + + `} + className="no-code" +/> + +```html + +``` +## Selected text format + +

+Specify how the selection is displayed with the `data-selected-text-format` attribute on a multiple select. + +The supported values are: + +* `values`: A comma delimited list of selected values (default) +* `count`: If one item is selected, then the option value is shown. If more than one is selected then the number of selected items is displayed, e.g. `2 of 6 selected` +* `count > x`: Where `x` is the number of items selected when the display format changes from `values` to `count` +* `static`: Always show the placeholder, regardless of selection + + + + + + `} +/> + +```html + +``` + + + + + + + `} +/> + +```html + +``` + +# Styling + +--- + +## Button classes + +You can set the button classes via the `data-style` attribute: + + + + +
+ +
+
+ +
+
+ +
+
+ +
`} +/> + +```html + + + + + + + + + +``` + +## Checkmark on selected option + +You can also show the checkmark icon on standard select boxes with the `show-tick` class: + + + + + + `} +/> + +```html + +``` + +## Menu arrow + +The Bootstrap menu arrow can be added with the `show-menu-arrow` class: + + + + + + `} +/> + +```html + +``` + +## Style individual options + +

+Classes and styles added to options are transferred to the select box: + + + + + + `} +/> + +```html + +``` + +```css +.special { + font-weight: bold !important; + color: #fff !important; + background: #bc0000 !important; + text-transform: uppercase; +} +``` + +## Width + +

+Wrap selects in grid columns, or any custom parent element, to easily enforce desired widths. + + +
+
+ +
+
+
+
+ +
+
+ +
+
+
+ +
+
+
+
+ +
+
+
+
+
+
+ +
+
+
+
+ +
+
+
`} +/> + +```html +
+
+
+ +
+
+
+``` + +
+ +Alternatively, use the `data-width` attribute to set the width of the select. Set `data-width` to `'auto'` to automatically adjust the width of the select to its widest option. `'fit'` automatically adjusts the width of the select to the width of its currently selected option. An exact value can also be specified, e.g., `300px` or `50%`. + + +
+
+ + +
+
+ +
+
+
+ + +
+
+
+
+
+
+ + +
+
+
+
+
+
+ + +
+
+
`} +/> + +```html + + + + +``` + +# Customize options + +--- + +## Icons + +Add an icon to an option or optgroup with the `data-icon` attribute: + +:::info Bootstrap 5 icons +Bootstrap 5 does not include an icon font. To use Font Awesome or another icon library, set `iconBase` and `tickIcon` to match that library. +::: + + + + + + + + `} +/> + +```html + +``` + +## Custom content + +Insert custom HTML into the option with the `data-content` attribute: + +:::warning Custom content is sanitized +This feature inserts HTML into the DOM. By default, it is sanitized using our built-in [sanitizer](./options#sanitizer). +::: + + + + + + + `} +/> + +```html + +``` + +## Subtext +Add subtext to an option or optgroup with the `data-subtext` attribute: + + + + + +
+ + With showSubtext set to true. +
`} +/> + +```html + +``` + +# Customize menu + +--- + +## Menu size + +The `size` option is set to `'auto'` by default. When `size` is set to `'auto'`, the menu always opens up to show as many items as the window will allow without being cut off. Set `size` to `false` to always show all items. The size of the menu can also be specifed using the `data-size` attribute. + + + + + + + + + + + + + + + + + + + + + + + + + + + `} +/> + +

+Specify a number for `data-size` to choose the maximum number of items to show in the menu. + + + + + + + + + + + `} +/> + +```html + +``` + +## Select/deselect all options + +Adds two buttons to the top of the menu - **Select All** & **Deselect All** with `data-actions-box="true"`. + + + + + + `} +/> + +```html + +``` + +## Divider + +Add `data-divider="true"` to an option to turn it into a divider. + + + + + + + + + + + + `} +/> + +```html + +``` + +## Menu header + +Add a header to the dropdown menu, e.g. `header: 'Select a condiment'` or `data-header="Select a condiment"` + + +
+ +
+ `} +/> + +```html + +``` + +## Container + +Append the select menu to a specific element, e.g. `container: 'body'` or `data-container=".main-content"`. This is useful if the select element is inside an element with `overflow: hidden`. + + +
+ + +
+
+ + +
+ `} + style={{ overflow: 'hidden' }} +/> + +```html +
+ + +
+``` + +## Dropup menu + +`dropupAuto` is set to true by default, which automatically determines whether or not the menu should display above or below the select box. If `dropupAuto` is set to false, manually make the select a dropup menu by adding the `.dropup` class to the select. + + + + + + `} +/> + +```html + +``` + +# Disabled + +--- + +## Disabled select box + + + + + + `} +/> + +```html + +``` + +## Disabled options + + + + + + `} +/> + +```html + +``` + +## Disabled option groups + + + + + + + + + + + + + `} +/> + +```html + +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0/index.md b/docs/versioned_docs/version-1.0/index.md new file mode 100644 index 00000000..8760e710 --- /dev/null +++ b/docs/versioned_docs/version-1.0/index.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 1 +title: Getting Started +description: Install and use the CrestApps bootstrap-select fork with Bootstrap 5+. +--- + +# Getting Started + +:::info CrestApps fork +This is the CrestApps fork of [snapappointments/bootstrap-select](https://github.com/snapappointments/bootstrap-select). It removes the jQuery dependency entirely, uses plain vanilla JavaScript, and supports Bootstrap 5+ only. Older Bootstrap and jQuery compatibility paths are intentionally out of scope so the library can stay small and forward-focused. +::: + +## Quick start + +bootstrap-select requires **Bootstrap 5+** (CSS and JS, including its bundled Popper). +jQuery is **not** required. + +Install with [npm](https://www.npmjs.com/package/crestapps-bootstrap-select): + +```sh +npm install crestapps-bootstrap-select bootstrap +``` + +Load Bootstrap 5 first, then bootstrap-select's CSS and JS (after Bootstrap's JavaScript): + +```html + + + + + + + + + + +``` + +## Using the CDN build + +After the package is published to npm, it will also be available through jsDelivr. +Prefer pinning an explicit package version in production: + +```html + + + + + + + +``` + +You can replace `@1.0.0` with the version you want to consume. During development, +`@latest` also works, but a fixed version is safer for production deployments. + +When loaded via a ` + + + + + + + +``` + +## Using the CDN build + +After the package is published to npm, it will also be available through jsDelivr. +Prefer pinning an explicit package version in production: + +```html + + + + + + + +``` + +You can replace `@1.1.0` with the version you want to consume. During development, +`@latest` also works, but a fixed version is safer for production deployments. + +When loaded via a `