svg-icons 0.1.0.3 → 0.4.0.0

raw patch · 4 files changed

+268/−18 lines, 4 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• src/Core/Geometry.hs +5/−1
• src/Icons.hs +238/−0
• src/Main.hs +22/−16
• svg-icons.cabal +3/−1

@@ -35,7 +35,7 @@ >  ! A.stroke "#0000FF"
 >  ! A.strokeWidth "10"
 
-will return a path element corresponding to a 
+will return a __path element__ corresponding to a 
 regular pentagon of radius 100 centered at point
 (200,300) filled in pink, green stroke and stroke
 width 10.
@@ -67,6 +67,8 @@ First species means that one vertice is skipped when joining vertices.
 The number of vertices must be strictly greater than 4.
 Can be customized with the usual [blaze-svg](https://hackage.haskell.org/package/blaze-svg) functions.
+
+__Returns a path__
 -}
 starPolygonFirstSpecies 
   :: Int             -- ^ number of vertices 
@@ -110,6 +112,8 @@ (so it would draw a pentagram), while this function's stroke
 runs outside the shape (so it would draw a star).
 There is no visual difference if you only fill the paths (with no stroke).
+
+__Returns a path__
 -}
 starOutline 
   :: Int             -- ^ number of vertices

@@ -0,0 +1,238 @@+{-# LANGUAGE     OverloadedStrings       #-}
+
+{- |
+This module just recopilates all other icon modules and re-exports them,
+so you don't have to import every icon module individually.
+You can just @import Icons@ and that will do. 
+This is also the perfect place to explain how these icons work. 
+
+You will have to do a little work before using them (explained below),
+and when you have the icon with the colors and stroke of your liking, 
+you have 2 options:
+
+  (1) If you are using [blaze-html](https://hackage.haskell.org/package/blaze-html)
+  for your frontend, everything in this package will work out-of-the-box for you.
+
+  (2) In any other case, you need to render the svg code into some file and work
+  with that. The `Core.Render` module provides you with 2 functions to do so, 
+  `renderSvgFiles` creates standard @.svg@ files, and `renderSvgReact` creates 
+  @.jsx@ files, suitable for the [React.js](https://reactjs.org/) javascript framework.
+
+
+** Preparing the icon (a little work):
+
+All icons are designed for a @viewbox "-1 -1 2 2"@ (a square centered at (0,0) and side = 2).
+However, the viewbox attribute must be assigned to the @\<svg\>@ tag, and the icons return a 
+@path@ or @g@ element (to allow composability of icons) so you must wrap it yourself with 
+the `svg` function from the @blaze-svg@ package. 
+
+For example, if you want to use the `warning` icon from `Icons.Computer`:
+
+>{-# LANGUAGE     OverloadedStrings       #-}
+>
+>import           Text.Blaze.Svg11 ((!))
+>import           Text.Blaze.Svg11 as S
+>import           Text.Blaze.Svg11.Attributes as A
+>
+>import Icons.Computer (warning)
+>
+>iconExample1 :: Svg
+>iconExample1 =
+>  S.svg
+>    ! A.viewbox "-1 -1 2 2"
+>    ! A.width  "200px"
+>    ! A.height "300px"
+>    $ warning
+>      ! A.fill   "pink"
+>      ! A.stroke "#777777"
+>      ! A.strokeWidth "0.03"
+
+You can render the result into a @.svg@ file and you will get:
+
+![icon example 1](https://raw.githubusercontent.com/RamiroPastor/SvgIcons/main/svg/examples/iconExample1.svg)
+
+Note that the functions in the previous example come from the 
+[blaze-svg](https://hackage.haskell.org/package/blaze-svg)
+package, so you will need to add it to your dependencies.
+
+There are some functions defined in module `Core.Style` that can make
+this process easier, in particular `stdDims`. Remember that you can avoid
+directly coding @fill@, @stroke@, @stroke-width@, @width@ or @height@ (and more)
+if you plan to use the svg inline (directly in your HTML code) and set those 
+properties with CSS (but it won't work for @\<img\>@ tags)
+
+Example with Core.Style:
+
+>import Core.Style
+>import Icons.Computer (accept)
+>
+>iconExample2 :: Svg
+>iconExample2 = 
+>  stdDims $ fillStyle accept
+
+Resulting svg:
+
+![icon example 2](https://raw.githubusercontent.com/RamiroPastor/SvgIcons/main/svg/examples/iconExample2.svg)
+
+All icon images in the documentation have been generated using
+the three style functions found in `Core.Style`, to expose how each icon looks
+with only stroke and no fill, only fill and no stroke, and both fill and stroke ("full" style).
+Most of them work with all 3 styles, but some are of no use in one of the three cases.
+
+** Composing Icons
+
+As said before, all icons aim to be composable (mix icons in the same svg element).
+Again, this is achieved by not wrapping them in the @\<svg\>@ tag in their definitions,
+and leaving the outmost tag of every icon (usually a @path@ or a @g@ element) free of 
+any transform attribute (and free of almost every other attribute too). Even those icons that
+have some transformation inside their code already, are wrapped with a clean @g@ tag to allow 
+for further transformations.
+
+Example:
+
+(remember that svg transformations are correctly applied from right to left, 
+as it should be because it's just function composition)
+
+>{-# LANGUAGE     OverloadedStrings       #-}
+>
+>import           Text.Blaze.Svg11 ((!))
+>import           Text.Blaze.Svg11 as S
+>import           Text.Blaze.Svg11.Attributes as A
+>
+>import Core.Geometry (starPolygonFirstSpecies)
+>import Icons.Cosmos (moonHalf, sun)
+>
+>
+>iconExample3 :: Svg
+>iconExample3 =
+>  S.svg
+>    ! A.viewbox "-3 -1 6 2"
+>    ! A.width  "300px"
+>    ! A.height "100px"
+>    $ S.g 
+>      ! A.strokeWidth "0.03"
+>      $ do
+>        moonHalf
+>          ! A.fill   "silver"
+>          ! A.stroke "gray"
+>          ! A.transform (translate (-2) 0 <> rotateAround (-30) 0 0 <> S.scale 0.7 0.7)
+>        sun 11
+>          ! A.fill   "yellow"
+>          ! A.stroke "orange"
+>          ! A.transform (translate ( 2) 0)
+>        starPolygonFirstSpecies 5 0.5 (0,0)
+>          ! A.fill   "sandybrown"
+>          ! A.stroke "crimson"
+
+Resulting svg composition:
+
+![icon example 2](https://raw.githubusercontent.com/RamiroPastor/SvgIcons/main/svg/examples/iconExample3.svg)
+
+** Multiple Fill Colors
+
+Currently, there is no way to fill different parts of one icon with different colors
+(or more exotic, animate specific parts of some icon).
+I am reluctant to parametrize colors as arguments for every icon, but this could be achieved
+by giving a unique id or class to each component of every icon. This is not on my priority list
+at this moment, but do not hesitate to ask for it if you need it. Or even better, do it yourself and
+ask for a branch merge on github.
+
+-}
+module Icons 
+  ( exampleIcons
+  , iconExample1
+  , iconExample2
+  , iconExample3
+  , module Icons.Business
+  , module Icons.Computer
+  , module Icons.Cosmos
+  , module Icons.Human
+  , module Icons.Math
+  , module Icons.Office
+  , module Icons.Religion
+  , module Icons.Textarea
+  , module Icons.Tools
+  ) where
+
+import           Text.Blaze.Svg11 ((!))
+import           Text.Blaze.Svg11 as S
+import           Text.Blaze.Svg11.Attributes as A
+
+import Core.Geometry
+import Core.Style
+import Icons.Business
+import Icons.Computer
+import Icons.Cosmos
+import Icons.Human
+import Icons.Math
+import Icons.Office
+import Icons.Religion
+import Icons.Textarea
+import Icons.Tools
+
+
+{- |
+A list with all the examples of this module, 
+together with appropriate names.
+
+exampleIcons :: [(String , Svg)]
+exampleIcons =
+  [ (,) "iconExample1" iconExample1
+  ]
+-}
+exampleIcons :: [(String , Svg)]
+exampleIcons =
+  [ (,) "iconExample1" iconExample1
+  , (,) "iconExample2" iconExample2
+  , (,) "iconExample3" iconExample3
+  ]
+
+
+{- |
+First example for the documentation above.
+-}
+iconExample1 :: Svg
+iconExample1 =
+  S.svg
+    ! A.viewbox "-1 -1 2 2"
+    ! A.width  "200px"
+    ! A.height "300px"
+    $ warning
+      ! A.fill   "pink"
+      ! A.stroke "#777777"
+      ! A.strokeWidth "0.03"
+
+
+
+{- |
+Second example for the documentation above.
+-}
+iconExample2 :: Svg
+iconExample2 = 
+  stdDims $ fillStyle accept
+
+
+
+{- |
+Third example for the documentation above.
+-}
+iconExample3 :: Svg
+iconExample3 =
+  S.svg
+    ! A.viewbox "-3 -1 6 2"
+    ! A.width  "300px"
+    ! A.height "100px"
+    $ S.g 
+      ! A.strokeWidth "0.03"
+      $ do
+        moonHalf
+          ! A.fill   "silver"
+          ! A.stroke "gray"
+          ! A.transform (translate (-2) 0 <> rotateAround (-30) 0 0 <> S.scale 0.7 0.7)
+        sun 11
+          ! A.fill   "yellow"
+          ! A.stroke "orange"
+          ! A.transform (translate ( 2) 0)
+        starPolygonFirstSpecies 5 0.5 (0,0)
+          ! A.fill   "sandybrown"
+          ! A.stroke "crimson"

@@ -8,6 +8,7 @@ import Core.Render
 import Core.Style
 import Core.Utils
+import Icons (exampleIcons)
 import Icons.Business (svgBusiness)
 import Icons.Computer (svgComputer)
 import Icons.Cosmos   (svgCosmos)
@@ -35,15 +36,21 @@   createDirectoryIfMissing False svgFolder
   removeDirectoryRecursive       svgFolder
   createDirectory                svgFolder
-  renderIcons   (svgFolder ++ "/icons/")
-  createDirectory (svgFolder ++ "/images")
-  renderCountryFlags (svgFolder ++ "/images/countryFlags/")
-  renderMosaics (svgFolder ++ "/images/mosaics/")
-  renderTest    (svgFolder ++ "/test/") (starRegular 7 0.9 (0,0))
+  renderExamples (svgFolder ++ "/examples/")
+  renderIcons    (svgFolder ++ "/icons/")
+  renderImages   (svgFolder ++ "/images/")
+  renderTest     (svgFolder ++ "/test/") (starRegular 7 0.9 (0,0))
   putStrLn "Svg files compiled correctly"
 
 
 
+renderExamples :: FilePath -> IO ()
+renderExamples path = do
+  createDirectory path
+  renderSvgFiles path exampleIcons
+
+
+
 renderIcons :: FilePath -> IO ()
 renderIcons path = 
   do
@@ -98,20 +105,19 @@     religionPath = path ++ "religion/"
     textareaPath = path ++ "textarea/"
     toolsPath    = path ++ "tools/"
-    
 
 
-renderCountryFlags :: FilePath -> IO ()
-renderCountryFlags path = do
-  createDirectory path
-  renderSvgFiles path countryFlags
 
-
-
-renderMosaics :: FilePath -> IO ()
-renderMosaics path = do
-  createDirectory path
-  renderSvgFiles path mosaicSample
+renderImages :: FilePath -> IO ()
+renderImages path = do
+    createDirectory path
+    createDirectory countryFlagsPath
+    createDirectory mosaicsPath
+    renderSvgFiles countryFlagsPath countryFlags
+    renderSvgFiles mosaicsPath      mosaicSample
+  where
+    countryFlagsPath = path ++ "countryFlags/"
+    mosaicsPath      = path ++ "mosaics/"
 
 
 

@@ -1,6 +1,6 @@ cabal-version:      2.4
 name:               svg-icons
-version:            0.1.0.3
+version:            0.4.0.0
 homepage:           https://github.com/RamiroPastor/SvgIcons
 license:            BSD-3-Clause
 license-file:       LICENSE
@@ -30,6 +30,7 @@     Core.Render,
     Core.Style,
     Core.Utils,
+    Icons,
     Icons.Business,
     Icons.Computer,
     Icons.Cosmos,
@@ -73,6 +74,7 @@     Core.Render,
     Core.Style,
     Core.Utils,
+    Icons,
     Icons.Business,
     Icons.Computer,
     Icons.Cosmos,