diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..39cec55 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,64 @@ +# Sample workflow for building and deploying a VitePress site to GitHub Pages +# +name: Deploy VitePress site to Pages + +on: + # Runs on pushes targeting the `main` branch. Change this to `master` if you're + # using the `master` branch as the default branch. + push: + branches: [main] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Not needed if lastUpdated is not enabled + # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm + # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm # or pnpm / yarn + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Install dependencies + run: npm ci # or pnpm install / yarn install / bun install + - name: Build with VitePress + run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index e6d4c90..d00fd2b 100644 --- a/.gitignore +++ b/.gitignore @@ -54,3 +54,7 @@ coverage Network Trash Folder Temporary Items .apdisk + +# Vitepress Docs +docs/.vitepress/dist +docs/.vitepress/cache \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7ba84c7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "editor.tabSize": 2, +} \ No newline at end of file diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 0000000..37e9206 --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,68 @@ +import { defineConfig } from 'vitepress' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "Nuxt Leaflet", + description: "Documentation for the Nuxt Leaflet module", + head: [['link', { rel: 'icon', href: '/Nuxt-Leaflet/favicon.ico' }]], + base: '/Nuxt-Leaflet/', + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + nav: [ + { text: 'Home', link: '/' }, + { text: 'Quick Start', link: '/getting-started/installation' }, + { text: 'Components', link: '/components/index' } + ], + + sidebar: [ + { + text: 'Getting Started', + items: [ + { text: 'Installation', link: '/getting-started/installation' }, + { text: 'Usage', link: '/getting-started/usage' } + ] + }, + { + text: 'Components', + items: [ + { text: 'Introduction', link: '/components/introduction' }, + { text: 'LCircle', link: '/components/l-circle' }, + { text: 'LCircleMarker', link: '/components/l-circle-marker' }, + { text: 'LControlAttribution', link: '/components/l-control-attribution' }, + { text: 'LControlLayers', link: '/components/l-control-layers' }, + { text: 'LControlScale', link: '/components/l-control-scale' }, + { text: 'LControlZoom', link: '/components/l-control-zoom' }, + { text: 'LControl', link: '/components/l-control' }, + { text: 'LFeatureGroup', link: '/components/l-feature-group' }, + { text: 'LGeoJson', link: '/components/l-geo-json' }, + { text: 'LGridLayer', link: '/components/l-grid-layer' }, + { text: 'LIcon', link: '/components/l-icon' }, + { text: 'LImageOverlay', link: '/components/l-image-overlay' }, + { text: 'LLayerGroup', link: '/components/l-layer-group' }, + { text: 'LMap', link: '/components/l-map' }, + { text: 'LMarker', link: '/components/l-marker' }, + { text: 'LPolygon', link: '/components/l-polygon' }, + { text: 'LPolyline', link: '/components/l-polyline' }, + { text: 'LPopup', link: '/components/l-popup' }, + { text: 'LRectangle', link: '/components/l-rectangle' }, + { text: 'LTileLayer', link: '/components/l-tile-layer' }, + { text: 'LTooltip', link: '/components/l-tooltip' }, + { text: 'LWmsTileLayer', link: '/components/l-wms-tile-layer' }, + ] + }, + { + text: 'Guide', + items: [ + { text: 'Using L', link: '/guide/using-l' }, + { text: 'Accessing Map Instance', link: '/guide/accessing-map-instance' }, + { text: 'Leaflet Draw (Experimental)', link: '/guide/leaflet-draw' } + ] + } + ], + + socialLinks: [ + { icon: 'github', link: 'https://github.com/Gugustinette/Nuxt-Leaflet' }, + { icon: 'npm', link: 'https://www.npmjs.com/package/nuxt3-leaflet' } + ] + } +}) diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css new file mode 100644 index 0000000..836b138 --- /dev/null +++ b/docs/.vitepress/theme/custom.css @@ -0,0 +1,49 @@ +/* Note : colors were taken from Nuxt branding */ +:root { + /* Brand Primary Color */ + --vp-c-brand-1: #03C169; + --vp-c-brand-2: #03C169; + + --vp-button-brand-bg: #03C169; + + /* Backgrounds */ + --vp-c-bg-alt: #F8FAFC; + --vp-c-bg-soft: #F8FAFC; + + /* Sidebar */ + --vp-sidebar-bg-color: #F8FAFC; + + /* Gray */ + --vp-c-gray-3: #F8FAFC; +} + +.dark { + /* Brand Primary Color */ + --vp-c-brand-1: #00DC82; + --vp-c-brand-2: #00DC82; + + --vp-button-brand-bg: #00DC82; + + /* Backgrounds */ + --vp-c-bg: #020420; + --vp-c-bg-alt: #121A31; + --vp-c-bg-elv: #020420; + --vp-c-bg-soft: #121A31; + + /* Sidebar */ + --vp-sidebar-bg-color: #020420; + + /* Gray */ + --vp-c-gray-3: #121A31; + + /* Primary Button */ + --vp-button-brand-text: #0F172A; + --vp-button-brand-hover-text: #0F172A; + --vp-button-brand-active-text: #0F172A; + --vp-button-brand-hover-bg: #03C169; +} + +/* Leaflet specific style */ +.leaflet-container { + z-index: 0 !important; +} diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js new file mode 100644 index 0000000..508d8b4 --- /dev/null +++ b/docs/.vitepress/theme/index.js @@ -0,0 +1,4 @@ +import DefaultTheme from 'vitepress/theme' +import './custom.css' + +export default DefaultTheme \ No newline at end of file diff --git a/docs/components/introduction.md b/docs/components/introduction.md new file mode 100644 index 0000000..c4ac312 --- /dev/null +++ b/docs/components/introduction.md @@ -0,0 +1,36 @@ +--- +outline: deep +--- + +::: info +Further documentation for these components was highly inspired from [Vue2 Leaflet Documentation](https://vue2-leaflet.netlify.app/components/), [Vue Leaflet Demo](https://github.com/vue-leaflet/vue-leaflet/tree/master/src/playground/views) and the original [Leaflet Documentation](https://leafletjs.com/). + +If you find any errors, please open an issue on the [GitHub repository](https://github.com/gugustinette/Nuxt-Leaflet). +Props and events can be verified by looking at the [vue-leaflet components](https://github.com/vue-leaflet/vue-leaflet/tree/master/src/components). +::: + +# Components + +The module automatically registers the following components from [Vue Leaflet](https://github.com/vue-leaflet/vue-leaflet) : + +- `LCircle` +- `LCircleMarker` +- `LControl` +- `LControlAttribution` +- `LControlLayers` +- `LControlScale` +- `LControlZoom` +- `LFeatureGroup` +- `LGeoJson` +- `LIcon` +- `LImageOverlay` +- `LLayerGroup` +- `LMap` +- `LMarker` +- `LPolygon` +- `LPolyline` +- `LPopup` +- `LRectangle` +- `LTileLayer` +- `LTooltip` +- `LWmsTileLayer` diff --git a/docs/components/l-circle-marker.md b/docs/components/l-circle-marker.md new file mode 100644 index 0000000..699fb3d --- /dev/null +++ b/docs/components/l-circle-marker.md @@ -0,0 +1,69 @@ +--- +outline: deep +--- + +# LCircleMarker + +> A circle of a fixed size with radius specified in pixels. + +## Demo + + + + + + + + +```vue{8-12} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| --------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | +| radius | Radius of the marker in pixels | Number | true | 10 | +| latLng | Latitude and longitude of the marker | object\|array as [L.LatLngExpression](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/45d34da16d9556b29be0469dbb66337735690feb/types/leaflet/v0/index.d.ts#L4) | true | [0, 0] | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| -------------- | ------- | -------------------------------------------------- | +| update:visible | boolean | Triggers when the visible prop needs to be updated | +| ready | object | Triggers when the component is ready | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| default | | | diff --git a/docs/components/l-circle.md b/docs/components/l-circle.md new file mode 100644 index 0000000..ce42e2b --- /dev/null +++ b/docs/components/l-circle.md @@ -0,0 +1,71 @@ +--- +outline: deep +--- + +# LCircle + +> Draw a path in the shape of a circle around a center positioned at `latLng` coordinates. + +> It's an approximation and starts to diverge from a real circle closer to the poles (due to projection distortion). + +## Demo + + + + + + + + +```vue{8-12} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| --------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | +| radius | Radius of the circle, in meters | Number | true | - | +| latLng | Latitude and longitude of the marker | object\|array as [L.LatLngExpression](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/45d34da16d9556b29be0469dbb66337735690feb/types/leaflet/v0/index.d.ts#L4) | true | [0, 0] | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| -------------- | ------- | -------------------------------------------------- | +| update:visible | boolean | Triggers when the visible prop needs to be updated | +| ready | object | Triggers when the component is ready | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| default | | | diff --git a/docs/components/l-control-attribution.md b/docs/components/l-control-attribution.md new file mode 100644 index 0000000..4a006f4 --- /dev/null +++ b/docs/components/l-control-attribution.md @@ -0,0 +1,53 @@ +--- +outline: deep +--- + +# LControlAttribution + +> The attribution control allows you to display attribution data in a small text bos on a map. + +## Demo + + + + + + + + +```vue{8} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| --------- | --------------------------------------------------------------------- | --------------- | -------- | --------- | +| prefix | The HTML text shown before the attributions. Pass `false` to disable. | String\|boolean | - | 'Leaflet' | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| ---------- | ------ | ------------------------------------ | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-control-layers.md b/docs/components/l-control-layers.md new file mode 100644 index 0000000..84f0795 --- /dev/null +++ b/docs/components/l-control-layers.md @@ -0,0 +1,57 @@ +--- +outline: deep +--- + +# LControlLayers + +> The layers control gives users the ability to switch between different base layers and switch overlays on/off. + +## Demo + + + + + + + + +```vue{8} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ------- | +| collapsed | If `true`, the control will be collapsed into an icon and expanded on mouse hover, touch, or keyboard activation. | Boolean | - | true | +| autoZIndex | If `true`, the control will assing zIndexes in increasing order to all of its layers so that the order is preserved when switching them on/off. | Boolean | - | true | +| hideSingleBase | If `true`, the base layers in the control will be hidden when there is only one. | Boolean | - | false | +| sortLayers | Whether to sort the layers. When `false`, layers will keep the order in which they were added to the control. | Boolean | - | false | +| sortFunction | A [compare function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) that will be used for sorting the layers, when `sortLayers` is `true`. The function receives both the [L.Layer](https://leafletjs.com/reference.html#layer) instances and their names, as in `sortFunction(layerA, layerB, nameA, nameB)`. By default, it sorts layers alphabetically by their name. | Function | - | * | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| ---------- | ------ | ------------------------------------ | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-control-scale.md b/docs/components/l-control-scale.md new file mode 100644 index 0000000..5b54f0b --- /dev/null +++ b/docs/components/l-control-scale.md @@ -0,0 +1,56 @@ +--- +outline: deep +--- + +# LControlScale + +> A simple scale control that shows the scale of the current center of screen in metric (m/km) and imperial (mi/ft) systems. + +## Demo + + + + + + + + +```vue{8} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| -------------- | -------------------------------------------------------------------------------------------------------------- | ------- | -------- | ------- | +| maxWidth | Maximum width of the control in pixels. The width is set dynamically to show round values (eg. 100, 200, 500). | Number | - | 100 | +| metric | Whether to show the metric scale line (m/km). | Boolean | - | true | +| imperial | Whether to show the imperial scale line (mi/ft). | Boolean | - | true | +| updateWhenIdle | If `true`, the control is updated on [moveend](https://leafletjs.com/reference.html#map-moveend), otherwise it's always up-to-date (updated on [move](https://leafletjs.com/reference.html#map-move)). | Boolean | - | false | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| ---------- | ------ | ------------------------------------ | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-control-zoom.md b/docs/components/l-control-zoom.md new file mode 100644 index 0000000..d4e81b3 --- /dev/null +++ b/docs/components/l-control-zoom.md @@ -0,0 +1,56 @@ +--- +outline: deep +--- + +# LControlZoom + +> A basic zoom control with two buttons (zoom in and zoom out). + +## Demo + + + + + + + + +```vue{8} + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| ------------ | -------------------------------------- | ------ | -------- | ---------- | +| zoomInText | The text set on the 'zoom in' button | String | - | '+' | +| zoomInTitle | The title set on the 'zoom in' button | String | - | 'Zoom in' | +| zoomOutText | The text set on the 'zoom out' button | String | - | '-' | +| zoomOutTitle | The title set on the 'zoom out' button | String | - | 'Zoom out' | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| ---------- | ------ | ------------------------------------ | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-control.md b/docs/components/l-control.md new file mode 100644 index 0000000..9c9d1ac --- /dev/null +++ b/docs/components/l-control.md @@ -0,0 +1,80 @@ +--- +outline: deep +--- + +# LControl + +> Base component for implementing map controls. Handles positioning. All other controls extend from this component. + +## Demo + + + + + + + + + + +```vue{8-13} + + + + + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| ------------------------ | ----------- | ------- | -------- | ------- | +| disableClickPropagation | | Boolean | - | true | +| disableScrollPropagation | | Boolean | - | false | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| ---------- | ------ | ------------------------------------ | +| ready | object | Triggers when the component is ready | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| default | | | diff --git a/docs/components/l-feature-group.md b/docs/components/l-feature-group.md new file mode 100644 index 0000000..08c86c5 --- /dev/null +++ b/docs/components/l-feature-group.md @@ -0,0 +1,66 @@ +--- +outline: deep +--- + +# LFeatureGroup + +> Extended [LLayerGroup](/components/l-layer-group.html) that makes it easier to do the same thing to all its member layers. + +::: warning +This still needs better documentation and examples. +::: + +## Demo + + + + + + + + + + +```vue + + + + + + +``` + +## Props + +This component does not have any specific props. + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| -------------- | ------- | -------------------------------------------------- | +| update:visible | boolean | Triggers when the visible prop needs to be updated | +| ready | object | Triggers when the component is ready | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| default | | | diff --git a/docs/components/l-geo-json.md b/docs/components/l-geo-json.md new file mode 100644 index 0000000..d272b69 --- /dev/null +++ b/docs/components/l-geo-json.md @@ -0,0 +1,91 @@ +--- +outline: deep +--- + +# LGeoJson + +> Represents a GeoJSON object or an array of GeoJSON objects. + +## Demo + + + + + + + + +```vue{8-11,14-28} + + + + + + +``` + + +## Props + +| Prop name | Description | Type | Required | Default | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------- | ------- | +| geojson | Should be an object in GeoJSON format (or an array of GeoJSON objects) that will be displayed on the map | Object\|Array as GeoJsonObject | GeoJsonObject[] | - | () => ({}) +| optionsStyle | A Function defining the styling for GeoJSON lines and polygons. See more in [original Leaflet documentation](https://leafletjs.com/reference.html#geojson-style) | Function as L.StyleFunction | - | * | + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| -------------- | ------- | -------------------------------------------------- | +| update:visible | boolean | Triggers when the visible prop needs to be updated | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-grid-layer.md b/docs/components/l-grid-layer.md new file mode 100644 index 0000000..69e886d --- /dev/null +++ b/docs/components/l-grid-layer.md @@ -0,0 +1,93 @@ +--- +outline: deep +--- + +# LGridLayer + +> Creates a map layer where each tile is an instantiated Vue component. +> Each tile component is given `coords` props by `LGridLayer` to indicate +> the zoom level and position of the tile +> (see https://leafletjs.com/examples/extending/extending-2-layers.html#lgridlayer-and-dom-elements). + +::: warning + + From [Vue Leaflet](https://github.com/vue-leaflet/vue-leaflet/blob/master/src/playground/views/GridLayerDemo.vue) : + + TODO NEXT: While sorting out type errors in LGridLayer.vue, I realized I'm not sure + how or even if its infrastructure is particularly used well. In Vue2Leaflet, + you could pass an arbitrary Vue component to the LGridLayer, to be rendered + for each tile with its coords passed as props. But that doesn't seem set up here. + Should we replicate V2L exactly here? Set things up so that the LGridLayer's $slot + can be where/how the component is setup/configured/passed/added? Simply stick with + the `childRender` prop and simplify some of the logic in LGridLayer.vue? +::: + +## Demo + + + + + + + + +```vue{8-10,13-28} + + + + + + +``` + +## Props + + + +### Inherited props + + + +## Events + +| Event name | Type | Description | +| -------------- | ------- | -------------------------------------------------- | +| update:visible | boolean | Triggers when the visible prop needs to be updated | +| ready | object | Triggers when the component is ready | diff --git a/docs/components/l-icon.md b/docs/components/l-icon.md new file mode 100644 index 0000000..1a946aa --- /dev/null +++ b/docs/components/l-icon.md @@ -0,0 +1,149 @@ +--- +outline: deep +--- + +# LIcon + +> Easy and reactive way to configure the icon of a marker + +## Demo + + + + + + + + + + + + + ★ + + + + + Hello, Map! + + + + + + + + +```vue + + + + + +``` + +## Props + +| Prop name | Description | Type | Required | Default | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------- | ------- | +| iconUrl | The URL to the icon image (absolute or relative to your script path) | String | true | null | +| iconRetinaUrl | The URL to a retina sized version of the icon image (absolute or relative to your script path). Used for Retina screen devices. | String | - | null | +| iconSize | Size of the icon image in pixels | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | null | +| iconAnchor | The coordinates of the "tip" of the icon (relative to its top left corner). The icon will be aligned so that this point is at the marker's geographical location. Centered by default if size is specified, also can be set in CSS with negative margins. | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | null | +| popupAnchor | The coordinates of the point from which popups will "open", relative to the icon anchor | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | [0, 0] | +| tooltipAnchor | The coordinates of the point from which tooltips will "open", relative to the icon anchor | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | [0, 0] | +| shadowUrl | The URL to the icon shadow image. If not specified, no shadow image will be created | String | - | null | +| shadowRetinaUrl | | String | - | null | +| shadowSize | Size of the shadow image in pixels | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | null | +| shadowAnchor | The coordinates of the "tip" of the shadow (relative to its top left corner) (the same as iconAnchor if not specified) | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | null | +| bgPos | | Object\|Array as [L.PointExpression](https://leafletjs.com/reference.html#point) | - | [0, 0] | +| className | A custom class name to assign to both icon and shadow images. Empty by default. | String | - | '' | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| default | | | diff --git a/docs/components/l-image-overlay.md b/docs/components/l-image-overlay.md new file mode 100644 index 0000000..e92622b --- /dev/null +++ b/docs/components/l-image-overlay.md @@ -0,0 +1,203 @@ +--- +outline: deep +--- + +# LImageOverlay + +> Used to load and display a single image over specific bounds of the map. + +## Demo + +::: warning +The demo still needs to be fixed. +::: + + + + + + + + {{ idx }} + + + + + + + + + + + + +
+

Markers

+ +
+ +```vue +